ZATCA Phase 2 Common Errors and How to Fix Them (2026)

The most common ZATCA Phase 2 rejection reasons in 2026 are PIH (Previous Invoice Hash) mismatch, signing with the Compliance certificate in production, TLV QR length-byte miscalculation on Arabic text, ICV gaps, Arabic seller name not matching the VAT record, and schema validation errors against the UBL 2.1 KSA profile. Each has a deterministic fix below.

Macro context — why rejections happen

ZATCA validates each invoice in two passes.

ZATCA validates each invoice in two passes. The first is schema: does the XML conform to UBL 2.1 with the KSA extensions? The second is business rule: do the cryptographic, sequencing, and identity fields agree with what ZATCA already has on file? Schema errors are loud and easy to fix; business-rule errors look identical at first glance (same HTTP 400) but root-cause in completely different layers. This catalogue separates them.

1. PIH (Previous Invoice Hash) mismatch

Symptom: ZATCA returns a business-rule error referencing the previous-invoice-hash field.

Symptom: ZATCA returns a business-rule error referencing the previous-invoice-hash field.

Cause: the invoice's PIH field does not match the SHA-256 hash of the actual previous cleared invoice. Triggered by parallel issuance from two devices sharing one CSID, by a local void without re-sync, or by replaying an invoice across environments.

Fix: re-fetch the last cleared invoice from ZATCA, recompute the chain from that point, resend. Architecturally: enforce one CSID per Solution Unit and serialise issuance per CSID.

2. XAdES signature invalid

Symptom: signature validation failed.

Symptom: signature validation failed.

Cause: usually one of (a) signing before canonicalisation, (b) signing with the Compliance CSID in production, or (c) wrong digest algorithm in the SignedInfo block.

Fix: apply XAdES B-B after XML canonicalisation, confirm the keystore alias points at the Production CSID, and use SHA-256 for both the reference digest and the signature.

3. TLV QR length-byte mismatch

Symptom: the QR scans but ZATCA's verifier reports a length-mismatch error.

Symptom: the QR scans but ZATCA's verifier reports a length-mismatch error.

Cause: a TLV tag's length byte does not equal the UTF-8 byte length of the value. JavaScript's string.length is UTF-16 code units; one Arabic character is typically two UTF-8 bytes.

Fix: compute the length on Buffer.byteLength(value, 'utf8') (Node) or equivalent. Verify the encoded QR with ZATCA's reference decoder before going live.

4. Timestamp skew

Symptom: invoice issue date in the future or too old to clear.

Symptom: invoice issue date in the future or too old to clear.

Cause: server clock drift, or IssueTime encoded in local time without a timezone offset.

Fix: NTP-sync to UTC, always emit IssueTime as ISO-8601 with an explicit +03:00 offset for KSA, never local-naive.

5. Arabic seller name does not match VAT record

Symptom: compliance check fails with a seller-name-mismatch error.

Symptom: compliance check fails with a seller-name-mismatch error.

Cause: the Arabic legal name on the invoice differs by even one character (extra space, missing diacritic, normalisation form NFC vs NFD) from the name registered against the VAT number at ZATCA.

Fix: copy the Arabic name from the VAT certificate verbatim, store NFC-normalised, and treat it as the single source of truth for every invoice and the CSR.

6. Schema validation: missing KSA extension fields

Symptom: schema validation failed against the UBL 2. 1 KSA profile.

Symptom: schema validation failed against the UBL 2.1 KSA profile.

Cause: the platform is sending base UBL 2.1 without the ZATCA KSA extensions (additional document references, profile ID, customisation ID).

Fix: declare ProfileID as reporting:1.0 (Simplified) or standard:1.0 (Standard), include the KSA AdditionalDocumentReference blocks (ICV, PIH, QR), and validate against the ZATCA-published XSD before submission.

7. ICV (Invoice Counter Value) gap

Symptom: ICV must be sequential.

Symptom: ICV must be sequential.

Cause: the integer ICV (per Solution Unit) skipped a number. ZATCA requires strict sequential numbering with no gaps; database row IDs and any value subject to rollback will leave gaps.

Fix: allocate the ICV from a dedicated atomic counter (Postgres sequence, Redis INCR, or a transactional row-lock) committed only when the invoice is finalised.

8. Missing or wrong ProfileID

Symptom: invalid ProfileID for invoice type.

Symptom: invalid ProfileID for invoice type.

Cause: the document declares standard:1.0 but the routing flag indicates a B2C transaction, or vice versa.

Fix: derive ProfileID strictly from invoice type — never from user input. Standard Tax Invoices and their notes use standard:1.0; Simplified Tax Invoices and their notes use reporting:1.0.

9. CSR field mismatch on onboarding

Symptom: onboarding fails at the Compliance CSID exchange step.

Symptom: onboarding fails at the Compliance CSID exchange step.

Cause: the CSR's Common Name, Organisation Identifier (CRN), or Business Category does not match what ZATCA has on file for the VAT number.

Fix: fetch the canonical values from the VAT certificate, regenerate the CSR with those values exactly, and try again. There is no override.

10. UUID reuse across invoices

Symptom: duplicate invoice UUID.

Symptom: duplicate invoice UUID.

Cause: the UBL UUID element was re-emitted from a cached template instead of regenerated.

Fix: generate a fresh v4 UUID per invoice at the moment of finalisation, never at template build time.

How to debug a rejection methodically

Capture the full ZATCA response body, not just the HTTP status — the error array contains both code and human-readable category. Re-validate the XML against the ZATCA-published XSD locally before resubmitting.

1. Capture the full ZATCA response body, not just the HTTP status — the error array contains both code and human-readable category.
2. Re-validate the XML against the ZATCA-published XSD locally before resubmitting.
3. Decode the TLV QR with ZATCA's reference tool to confirm tag/length/value integrity.
4. Verify the signing certificate chain ends at the ZATCA root, not the Compliance test chain.
5. If PIH errors persist, dump the last-cleared invoice from ZATCA and recompute the chain locally — never trust your local cache as the source of truth.

Key takeaways

Key takeaways includes: Schema errors and business-rule errors look identical at HTTP level; separate them before debugging. The hash chain (PIH) and the production certificate (CSID) cause more production rejections than any other pair of fields.

• Schema errors and business-rule errors look identical at HTTP level; separate them before debugging.
• The hash chain (PIH) and the production certificate (CSID) cause more production rejections than any other pair of fields.
• Arabic-text length and normalisation issues are silent killers — always validate the QR with ZATCA's decoder before go-live.
• The ZATCA Fatoora Developer Community on Discourse is the fastest place to confirm a non-obvious error.

Authority sources

• ZATCA — E-Invoice specifications
• ZATCA — TLV QR Code Creation guide (PDF)
• ZATCA — E-invoicing Detailed Technical Guidelines (PDF)
• ZATCA Fatoora Developer Community
• Developer Community — Understanding PIH and ICV

Related reading

The mandate context is in ZATCA Phase 2 explained, the implementation flow that avoids most of these errors is in How to comply with ZATCA Phase 2, and the migration baseline is ZATCA Phase 1 vs Phase 2. The mandate page is /e-invoicing/zatca-phase-2.

The mandate context is in ZATCA Phase 2 explained, the implementation flow that avoids most of these errors is in How to comply with ZATCA Phase 2, and the migration baseline is ZATCA Phase 1 vs Phase 2. The mandate page is /e-invoicing/zatca-phase-2.