## TL;DR

ZATCA's hash mismatch means the invoice hash you submitted does not match the hash ZATCA computed from your canonical invoice XML: something changed the bytes between hashing and submission (whitespace, encoding, re-serialization). Fix the pipeline so the exact canonical bytes you hashed are the bytes you submit: hash after final canonicalization, submit those bytes unchanged, and never re-serialize in between. Log both hashes on failure so you can diff. Test against the ZATCA sandbox with the same canonicalization code path as production.

## The query

```text
Saudi ZATCA e-invoice "hash mismatch" errors: how to fix
```

## Use this when

- ZATCA clearance failing with hash mismatch
- E-invoice hash validation errors in Saudi Arabia
- Canonicalization issues in ZATCA integration

## Not for

- Onboarding or certificate errors (different stage)
- Invoice content rejections (business rule failures)

## Steps

1. Capture the submitted XML bytes and the hash you sent.
   Expected output: You have the actual artifacts to compare.
2. Recompute the hash locally from those exact bytes.
   Expected output: You see whether your hash matches your bytes.
3. Find the mutation: re-serialization, whitespace, or encoding change between hash and submit.
   Expected output: The pipeline stage that alters bytes is identified.
4. Restructure so canonicalization happens once and the bytes are frozen through submission.
   Expected output: Hash and submit operate on identical bytes.
5. Replay the failing invoices through the fixed path in the sandbox first.
   Expected output: The fix is proven before production resubmission.

## Variant phrasings

### ZATCA hash mismatch e-invoice

### Saudi e-invoice hash validation failed

### ZATCA canonicalization hash error

## Root cause

The hash is a fingerprint of exact bytes, so any transformation after hashing (pretty-printing, encoding normalization, XML library re-serialization) invalidates it even though the invoice 'looks' identical. The discipline is hash-last, submit-frozen.

## Edge cases

- Previous invoice hash chaining (PIH) has the same fragility; protect that value too
- Clearance vs reporting flows both validate hashes; fix the shared code path

## Provenance

Resolved from the public thread: https://vectle.com/posts/pst_7zR6eAv3ZXIeL5wnTt-ayA