Why ZATCA rejects your QR code

The rule

The TLV length is a BER length, not a plain byte:

length < 128          one byte
128 ≤ length ≤ 255    0x81, then the length byte
256 ≤ length          0x82, then two bytes, big-endian

This is not our reading. It is settled on ZATCA’s own forum, by a developer whose QR code was rejected and who traced it to exactly this:

our code assumed that the maximum length of the value is 1 byte and therefore when the value was bigger than 127, we were not properly convert it to TLV value

https://zatca1.discourse.group/t/qr-code-rejected-when-tag-1-company-name-exceeds-127-characters/7202

Check your own QR

Paste the Base64 your encoder produces. Nothing is uploaded — this runs the same decoder that scored the table below, in your browser.

Results

Measured 2026-09-02. Downloads are npm’s last-month figure, fetched 2026-09-01.

What fails, and where

The fix

const berLength = (n) =>
  n < 0x80  ? [n] :
  n <= 0xFF ? [0x81, n] :
              [0x82, n >> 8, n & 0xFF];

const tlv = (tag, value) => {
  const bytes = Buffer.from(value, "utf-8");
  return Buffer.concat([Buffer.from([tag, ...berLength(bytes.length)]), bytes]);
};

A decoder must read the same forms. A single-byte reader sees 0x81 as a length of 129 and silently truncates the value — the same bug from the other side.

Or install one that already does it

The four lines above are enough if you only need the QR. If you also need Arabic text that survives a PDF — amounts that do not reverse, names that do not truncate — these two libraries do both. Not on npm yet; installable today from a release:

npm install https://github.com/opusstudiohq-max/arabic-invoice-mcp/releases/download/libs-v0.2.0/fatura-zatca-0.2.0.tgz

import { encodeZatcaQr, computeTotals, formatMinor } from "fatura-zatca";

const qr = encodeZatcaQr({
  sellerName: "مؤسسة عبد الرحمن العتيبي للتجارة والمقاولات",
  vatNumber: "310122393500003",
  timestamp: "2026-09-01T14:30:00Z",
  totalWithVat: "1150.00",
  vatAmount: "150.00",
});
// a 140-byte name emits 0x81 0x8C — the form ZATCA's validator accepts

fatura-zatca pulls nasq with it. Verified end to end from that URL in a clean project: correct length form, name intact after decoding, totals in halalas.

We found it in our own code first

We went to measure other packages, noticed one writing BER lengths, went to check which reading was right — and found our own code was wrong, in three places including our published checker tool. All were fixed before we measured anyone, and the runner refuses to write results at all if one of our engines fails.

It is not a JavaScript problem

The scores above cover npm, because that is what this harness can execute. But the same defect is in the most-starred ZATCA repositories on GitHub, in three other languages — including libraries published by major Saudi platforms:

All four measure the value in bytes — they clear the trap that catches most implementations — and then write that count in a single byte. The Go library states the premise outright:

// since the length could only be 1 byte, that means the maximum length for
// every field values is 255.
const maxValueLength = 255

So the error is not a slip in one ecosystem. It is a common reading of a spec sentence that says "one byte" — which is why it reaches 91.7% of measured npm downloads and the top of GitHub alike.

These four were read, not executed — there is no PHP, Ruby or Go runtime on the machine that produced this page. The quotes are literal from each repository's default branch. The npm scores above are executed.

Reported to the maintainers

A benchmark that finds a defect and does not tell its author is just gossip. Every finding was filed with a runnable reproduction and the fix:

Rules measured

Rerun it yourself

git clone https://github.com/opusstudiohq-max/arabic-invoice-mcp
cd arabic-invoice-mcp/zatca-qr-benchmark
npm install
node run.mjs --fetch && node build.mjs

Full method, the cases, and the nine adapters we got wrong on the first run: the English write-up.