Error Code 1011: QR Code With Missing Fields

Error code 1011 means one specific thing: the QR code on the electronic invoice does not carry all the mandatory fields required by Phase Two. The validator decodes the code, counts the tags inside it, finds some missing, rejects the invoice, and returns this code. The invoice may look complete on paper, and the code may scan visually without a problem, but the data layer inside it is incomplete — and that alone is enough to make it non-compliant. This guide isolates this exact error: its cause, how to detect it, how to fix it, and how to prevent it from recurring, within the ecosystem of Qoyod electronic invoicing.

We deliberately avoid mixing this error with other QR code errors here. Corrupted TLV encoding, faulty Base64 encoding, or visual scan failure are all separate faults with their own evidence. Error 1011 specifically says that the code’s structure is sound enough to read, but the number of tags is fewer than required. In other words: the code is decodable, but incomplete. This distinction is the key to correct diagnosis, and it saves you hours of searching in the wrong layer.

Before getting into the details, if you want to understand the sound structure of the code first, start from the guide the technical structure of the QR code in the invoice. And if you want a comprehensive panel of all QR code faults, review the guide QR code errors in the electronic invoice. And to see this error within the complete map of the Authority’s errors, return to the guide ZATCA e-invoicing errors.

What exactly does error code 1011 mean?

The QR code on the electronic invoice is not an image, but an encoded data string made of sequential fields, each field in a tag, length, and value format. The Phase Two specification requires the code to carry nine tags in order from 1 to 9. When the Fatoora platform application decodes the code and finds that one of these tags is missing, it triggers error 1011: QR code with missing fields.

The nine tags split into two clear groups. Tags 1 to 5 are core data that existed since Phase One: the seller’s name, the tax number, the timestamp, the invoice total including tax, and the value-added tax amount. Tags 6 to 9 were added by Phase Two, and they are technical tags related to the digital signature: the invoice hash value, the digital signature, the public key, and the Authority’s encrypted stamp. The absence of any one of the nine triggers the error, but the most common absence by a large margin falls in the second group, that is tags 6, 7, 8, and 9.

The reason is that these four tags are not data you write into fields, but values generated by the signing engine after the invoice is stamped. When the system generates the code with Phase One logic, or when the signing layer fails silently, the code is completed with only its first five tags and appears sound to the eye, while it is in fact missing four tags. That is why error 1011 is in most cases a symptom of a problem in the signing layer, not in writing the fields.

The Qoyod electronic invoicing software issues the code automatically with all nine tags complete on every simplified tax invoice, after linking your certificate once. But if you integrate through a custom API, import invoices from a legacy system, or write an invoicing engine in-house, this error may appear, and knowing its mechanism shortens diagnosis from hours to minutes.

The nine tags and which one causes error 1011

To diagnose the error precisely, you need to know what each tag represents and who generates it. This is the list of the nine tags in their mandatory order:

• Tag 1: the seller’s name, text matching the name registered in the tax certificate.
• Tag 2: the seller’s tax number, fifteen digits starting and ending with the digit 3.
• Tag 3: the invoice timestamp in the international date and time format.
• Tag 4: the invoice total including value-added tax.
• Tag 5: the value-added tax amount alone.
• Tag 6: the invoice hash value in Base64 format, linking the invoice to the chain of previous invoices to prevent tampering.
• Tag 7: the invoice’s digital signature generated with the private key.
• Tag 8: the corresponding public key, used by the reader to verify the signature.
• Tag 9: the Authority’s encrypted stamp, which is the Authority’s signature on the public key to prove it comes from an approved certificate.

Tags 1 to 5 are written by you directly from the invoice data, so their absence is rare and usually points to a flaw in building the fields. Tags 6 to 9, however, are not written by you; they are generated by the signing engine after linking the invoice to the Cryptographic Stamp Identifier (CSID) certificate registered with the Authority. That is why, when the validator triggers error 1011, the most likely case is that the missing tag is one of tags 6 to 9, and that the root cause is in the signing layer, not in writing the data.

This distinction guides your diagnosis directly. If the missing tag is one of tags 1 to 5, search in the field-building code and length calculation. And if the missing tag is one of tags 6 to 9, which is the most common, stop inspecting the field building and move immediately to the certificate state and the signing engine. This alone saves considerable effort, because many teams waste their time reviewing the field code while the problem was never there in the first place.

How do you detect the missing tag precisely?

Before you fix, you need to determine exactly which tag is missing. Error 1011 tells you there is a shortage, but it does not always specify which tag. So the first step is to decode the code locally and count its tags yourself instead of guessing.

Start by extracting the Base64-encoded text from the code, not by looking at the image. The text is what can be analyzed. Decode the Base64 to get the binary string, then parse the TLV structure byte by byte: read the first byte as a tag, the next as a length, then skip a number of bytes equal to the length to read the value, then return to the next tag. Record the numbers of the tags that appeared in order. If you see 1, 2, 3, 4, 5 and then the string stops, the missing tags are 6 to 9, and this confirms the problem is in the signing layer.

The following segment shows the output of decoding a sound code carrying its nine tags, versus the output of an incomplete code that triggers error 1011:

// sahih: al-ramz yahmil al-wusum al-tisaa kamila
{
  "tags_found": [1, 2, 3, 4, 5, 6, 7, 8, 9],
  "phase": 2,
  "valid": true
}

// khata 1011: nuqsan al-wusum 6-9 (tabaqat al-tawqee)
{
  "tags_found": [1, 2, 3, 4, 5],
  "phase": 1,
  "valid": false,
  "error_code": "1011",
  "missing": [6, 7, 8, 9]
}

Notice the essential difference: in the incomplete case, tags 1 to 5 appear entirely sound, which is why the code scans visually without a problem, while tags 6 to 9 are completely absent. This pattern — the first group present and the second entirely absent — is the distinctive signature of error 1011 caused by a signing layer that did not work. But if you find scattered absence, such as tag 3 alone missing while the rest are present, the root cause is different and points to a flaw in building a specific field.

If you do not have a ready decoding tool, build a small test suite that decodes the code and prints the list of tags. This tool is a simple investment that turns diagnosis from visual guessing into precise data inspection, and you become able to identify the missing tag in seconds instead of hours.

There is a practical detail worth noting during decoding. When tags 1 to 5 appear and then the string stops, look at the last byte you read: if the string ends completely after tag 5, this means the system did not generate the second group at all, which is the structural failure whose causes most likely trace to the signing layer or Phase One logic. But if you find extra bytes after tag 5 that do not form valid tags, the likelihood is that the second group was generated but was corrupted in writing, and this shifts the diagnosis toward an error in building the fields rather than the absence of a signature. Distinguishing between “not written” and “written but corrupted” greatly shortens the repair path.

Record the result of each decoding in a file that links the invoice number to the list of tags that appeared in it. When these records accumulate, the error pattern appears clearly: does the shortage occur in all invoices, or in the invoices of a specific branch, or after a specific date? A shortage in all invoices points to a general flaw in the system, a shortage in one branch points to an unlinked certificate for that branch, and a shortage that starts from a certain date usually points to a certificate expiry. This pattern analysis alone may identify the root cause before you open the code.

When is the missing tag from the first group?

Although the most common absence is in tags 6 to 9, it sometimes happens that one of tags 1 to 5 is missing. This mostly occurs when the system builds the fields manually and skips a field because its value is empty. For example, an invoice with a zero tax value may have the code skip tag 5, assuming that zero does not need a field, and this is a mistake: the tag is mandatory even if its value is zero. The result is a code with eight tags instead of nine, so the validator triggers error 1011.

Therefore, if decoding reveals that the missing tag is from the first group, inspect the field-building logic for a condition that skips the field when the value is empty or zero. The rule is that every one of the nine tags is always mandatory, and is never dropped merely because its value is zero or a short text.

The root causes of error 1011

After you identify the missing tag, you need to understand why it was absent. Error 1011 has multiple root causes, and each cause leads to a different fix.

The first cause: the system generates the code with Phase One logic. Some legacy systems or incomplete integrations still build the code with only five tags, because they were designed before Phase Two became mandatory and were not updated. Here there is no signing layer at all, so tags 6 to 9 are structurally absent, not incidentally. This is the clearest and most common of the causes in manually built systems.

The second cause: the certificate is unlinked or expired. Tags 6 to 9 depend on the Cryptographic Stamp Identifier (CSID) certificate registered with the Authority. If the certificate is not linked, or was linked and then expired, the signing engine has nothing with which to generate the signature, the public key, and the Authority’s stamp, so the tags are absent. Each device or branch needs its own certificate, and neglecting to link one of them is a recurring source of the error.

The third cause: the signing engine failed silently. Sometimes the certificate is sound but the signing step itself fails for a technical reason, such as a connection outage or a configuration error, so the system completes generating the code with only the available tags instead of halting the process. This silent failure is dangerous because it issues an incomplete invoice without a clear warning, so the problem is discovered late during auditing.

The fourth cause: skipping a mandatory field at an empty value. As we explained, the code may skip one of tags 1 to 5 when its value is zero or empty, so the code is missing a tag from the first group. This is a cause separate from the signing layer, and it is discovered by decoding the code as we described.

Identifying the correct root cause settles the direction of the fix. The first three causes are treated in the signing and certificate layer, and the fourth cause is treated in the field-building code. Confusing them leads to a fix in the wrong layer, so the error persists despite the work. The golden rule here is to prove the cause with evidence before you start fixing: decode a failing code, identify the missing tag, link it to the responsible layer, then act. Evidence-based diagnosis is always faster than guess-based fixing, however logical the guess may seem.

The fix step by step

The fix follows the root cause you identified. Here we present the two main paths in practical order.

The first path: missing tags 6 to 9 (the signing layer)

This path handles the most common case, when tags 1 to 5 appear and 6 to 9 are absent. Follow the steps in order:

• Verify that your system is configured for Phase Two. If it generates the code with only five tags, it is on Phase One logic and needs an update that adds the signing layer. Do not write tags 6 to 9 manually, as they are generated values, not data to be entered.
• Confirm that the Cryptographic Stamp Identifier (CSID) certificate is linked. Check that the certificate is registered with the Authority for every device or branch that issues invoices, and that it is valid and not expired.
• Inspect the signing engine log. Look for a silent failure in the signing step. If you find a signing error that did not halt code generation, address its root and halt code issuance when signing fails instead of completing it incompletely.
• Reissue the invoice after the fix. Invoices that were issued incomplete before the fix remain incomplete, so fixing the system is not enough without handling the affected invoices according to the Authority’s procedures.

The second path: missing tags 1 to 5 (field building)

This path handles the less common case, when one of the first five tags is missing:

• Inspect the field-building logic. Look for a condition that skips the field when its value is empty or zero, and remove it. Every tag is always mandatory.
• Confirm the tag is written even with a zero value. Tag 5, for example, is written even if the tax value is zero, with a length equal to the length of its actual value.
• Test with a zero-tax invoice. Add to your test suite an invoice with a zero tax value, because it exposes this specific fault that disappears in invoices with a positive tax.

In both paths, the closing rule is one: decode the code again after the fix and confirm that the tags appear in order from 1 to 9 without gaps before you consider the problem solved. Do not settle for the error disappearing from the validator’s message; instead, prove the tags are complete by decoding directly.

How do you prevent error 1011 from recurring?

The fix addresses the current case, but prevention spares you a recurrence of the problem on future invoices. These are practices that fortify your system against error 1011:

Halt issuance when signing fails. The most dangerous thing about this error is the silent failure that issues an incomplete invoice without warning. Make your system halt code issuance and trigger a clear alert whenever the signing step fails, instead of completing the code with the available tags. An invoice that was not issued is easier to remedy than an invoice issued incomplete.

Monitor certificate validity. Set an alert well before the Cryptographic Stamp Identifier certificate expires, because its expiry turns all subsequent invoices incomplete all at once. Track the expiry date of each certificate for every device and branch.

Add an automatic check after every issuance. Make the system decode the code as soon as it is generated and automatically verify the presence of the nine tags before printing or sending the invoice. This simple check catches the shortage at its moment instead of discovering it during a field audit.

Test with varied invoice types. Include in your test suite an invoice with zero tax, another with positive tax, and an invoice with a long Arabic seller name, because these cases expose different categories of shortage before they reach the customer.

Document the linking of each certificate for every device and branch. In multi-branch or multi-device establishments, tag shortage often occurs on one device whose certificate linking was forgotten while the rest of the devices were linked. Keep a table showing each device that issues invoices, its certificate state, and the date it was linked and expires. This table turns a problem that might take a day to trace into a single glance that reveals the affected device immediately.

The simplest way to eliminate this category of errors entirely is to use a system that handles generating the code and its nine tags on your behalf. When the code is built manually or through an incomplete integration, the possibilities of a shortage remain no matter how hard you try to inspect, because every manual step adds a potential point of failure. An integrated system transfers this entire responsibility from your team to a layer that generates the code and verifies its completeness before issuing the invoice, so error 1011 becomes a negated possibility rather than a problem to manage.

How Qoyod helps you avoid error 1011

Error 1011 arises when the code is built manually or through an integration that does not complete the signing layer. The Qoyod electronic invoicing software handles building the code on your behalf on every simplified tax invoice, writing the five core tags from the invoice data and generating the hash, signature, public key, and Authority stamp values after linking the Cryptographic Stamp Identifier (CSID) certificate registered with the Authority, then issuing the code with all nine tags complete.

This means the signing layer works automatically on every invoice, so the shortage category represented by error 1011 does not appear at all. Qoyod manages the certificate and guides you through linking it once, and your role is limited to registering your certificate with the Authority, a step the system leads you through step by step. This way the incomplete-invoice case that drains development teams’ time in manually built systems disappears.

Frequently asked questions

What exactly does error code 1011 mean?

It means the QR code on the invoice does not carry all nine mandatory tags required by Phase Two. The validator decodes the code and finds one or more missing tags, so it rejects the invoice and triggers this error. The code is readable but has missing fields.

Which tags are usually missing in error 1011?

The most common is the absence of tags 6, 7, 8, and 9: the hash value, the signature, the public key, and the Authority stamp. These are tags generated by the signing engine, so their absence points to a problem in the signing layer or the certificate, not in building the fields.

How do I know exactly which tag is missing?

Decode the code locally instead of looking at the image: decode the Base64, then parse the TLV structure and count the tags in order. If 1 to 5 appear and 6 to 9 are absent, the problem is in the signing layer. And if a scattered tag from 1 to 5 is missing, the problem is in building the fields.

Why does the code scan visually even though it has missing fields?

Because the visual scan reads only the image, and the image is sound. The shortage is in the data layer, not in the image, so the code scans successfully while verification fails when counting the tags. The soundness of the image does not mean the data is complete.

Is fixing the system enough to handle previous incomplete invoices?

No. Fixing the system prevents the error from recurring on future invoices, but the invoices that were issued incomplete remain incomplete and need to be handled according to the Authority’s procedures. Handle the affected invoices alongside fixing the root cause.

Do I need to build the QR code manually in Qoyod?

No. Qoyod issues the code automatically with all nine tags complete on every simplified tax invoice, after linking the Cryptographic Stamp Identifier (CSID) certificate once, so error 1011 does not appear at all.