Error Code 1017: Mandatory Header Field Missing

If the Fatoora platform rejects your invoice and returns error code 1017, the message is telling you that one of the mandatory fields in the invoice header is missing. The header is the top of the document that carries its identity: the invoice ID, the unique identifier UUID, the issue date and time, the invoice type code, the currency, and the seller data. The absence of any of these fields stops the invoice at the validation gate before it ever reaches any calculation or signing rule. This page explains the error from its root: exactly which fields the header means, how to read the rejection message, how to identify the missing field and fix it, and how to prevent it from recurring for good.

This guide is part of the ZATCA e-invoicing error reference, within the e-invoicing system by Qoyod. The target audience is the developer, integration analyst, or accountant who manages technical issuance and wants a precise understanding of the cause, not just a surface-level step.

What error code 1017 means exactly

Error code 1017 is a rejection at the invoice structure validation level, specifically at the header level. The invoice header (Invoice Header) is the set of fields that define the invoice as a whole, before the goods and services line items and before the detailed seller and buyer blocks. When the platform receives the document, it first checks that every mandatory field in the header is present and in its place. If a single field is missing, it stops the invoice immediately and returns code 1017 with a message indicating that the header is missing mandatory fields.

The key thing to understand is that this rejection is structural, not arithmetic. The platform is not yet looking at the correctness of the numbers, the tax logic, or the signature; it stops at the first barrier: is the header complete? The fields that validation monitors at this layer are known and defined in the ZATCA specification, and they include the invoice ID, the unique identifier UUID, the issue date and time, the invoice type code, the currency code, and the core fields of the seller identity inside the header. Any field from this list, if it is missing, left empty, or placed in the wrong position, produces code 1017.

This distinction is practical. Once you know the rejection is at the header layer, you don’t go auditing rounding logic or the VAT rate; you go straight to the top of the document and check the presence of the six core fields. This alone cuts diagnosis from minutes to seconds.

The mandatory fields in the header

Before you diagnose a missing field, you need to know which fields validation monitors in the header. The following table details each field, its position in the XML file, and its role. Keep it close, as it is the first thing you return to when code 1017 appears.

Note that the invoice type code InvoiceTypeCode carries additional attributes that determine whether the invoice is standard or simplified, but its absence as a whole, not its wrong value, is what produces code 1017. Its wrong value is a separate matter handled by a different code. Here we are talking about absence alone.

How to read the rejection message

When the invoice is rejected, the platform returns a response carrying the invoice status and a list of validation errors. Each error carries a code, a category, and a message. The following block is an illustrative example of a rejection response caused by the absence of the unique identifier UUID from the header. Copy it and compare it with the response structure your system returns.

{
  "validationResults": {
    "infoMessages": [
      {
        "type": "INFO",
        "code": "XSD_ZATCA_VALID",
        "category": "XSD validation",
        "message": "Complied with UBL 2.1 standards"
      }
    ],
    "warningMessages": [],
    "errorMessages": [
      {
        "type": "ERROR",
        "code": "1017",
        "category": "Invoice header validation",
        "message": "A mandatory header field is missing from the invoice."
      }
    ],
    "status": "ERROR"
  },
  "clearanceStatus": "NOT_CLEARED",
  "clearedInvoice": null
}

The keys that matter to you when reading:

• status with a value of ERROR means an outright rejection, as the invoice will not be approved until it is corrected.
• code with a value of 1017 is what you rely on to classify the error. Tie your system’s logic to the code, not the descriptive text, because the code is fixed while the text may be phrased in different ways.
• category with a value of Invoice header validation confirms that the fault is in the header, not in the line items or the calculation.
• infoMessages here tells you that the document is syntactically sound and compliant with UBL 2.1, meaning the problem is not in the XML format itself but in the absence of a specific field.

If some integrations return a message that explicitly names the missing field, rely on it directly. And if it does not name it, you must manually inspect the six fields in the order given in the table above. Most likely the missing one is UUID or the issue time, because they are the two fields most prone to dropping out in automated generation.

How each header field fails on its own

Code 1017 is a single code that covers six fields, but each field has its own failure pattern and a different data source. Knowing the expected pattern for each field shortens diagnosis, because when you see the code you go straight to the field most likely to be missing in your system’s context.

Invoice ID ID. It rarely goes missing because it is the visible invoice number, and it is usually auto-generated. But it drops out when the system relies on a sequence that resets or fails to generate the next number when there is a conflict in the database, so the invoice comes out with an empty ID field. Inspect the sequence generation logic if you see this field missing.

Unique identifier UUID. The field most prone to dropping out in manual integrations. The reason is that some systems generate the UUID in a step separate from creating the invoice, so if that step fails or is executed under a condition that was not met, the invoice comes out with no unique identifier. Do not confuse it with the invoice ID ID: the first is a global technical identifier for the Authority, and the second is the invoice number visible to the reader. Both are mandatory and both fall under code 1017 when missing.

Issue date and time IssueDate / IssueTime. The field that confuses more than it appears, because the date usually passes while the time drops out. Many templates fill IssueDate from a date field in the database, but leave IssueTime empty because they never stored the time in the first place. The result is an invoice with a date but no time that the platform rejects. Handle both fields together from a single time source.

Invoice type code InvoiceTypeCode. Here a precise distinction is required: the absence of the field as a whole produces code 1017, whereas its presence with a wrong value produces a different code concerning type classification. If you see 1017 tied to this field, the problem is that the element itself was not written in the header, not that its value is wrong. Check that the template always writes the element, even with a correct default value.

Currency code DocumentCurrencyCode. In domestic invoices its value is SAR. This field drops out when the template assumes the currency implicitly without writing it explicitly in the header, or when it relies on a currency setting that was not configured in the entity’s account. Write the currency explicitly in every invoice instead of relying on an implicit assumption.

Seller data AccountingSupplierParty. The identity block of the issuing entity as it appears at the top of the document. It comes out incomplete when the entity does not complete its identity data in the system setup, so the template builds a seller block without the core fields. This field ties code 1017 directly to the initial setup stage, not to the moment of issuance.

What the incomplete header looks like in the XML file

The following block is a simplified example of a header from which the unique identifier UUID element has dropped out. Note that all the other elements are present and sound, but the absence of a single line is enough to reject the entire invoice with code 1017. Compare this structure with what your system generates.

<Invoice>
  <cbc:ID>INV-2026-00417</cbc:ID>
  <!-- cbc:UUID missing here: this is the cause of code 1017 -->
  <cbc:IssueDate>2026-06-24</cbc:IssueDate>
  <cbc:IssueTime>14:35:00</cbc:IssueTime>
  <cbc:InvoiceTypeCode name="0100000">388</cbc:InvoiceTypeCode>
  <cbc:DocumentCurrencyCode>SAR</cbc:DocumentCurrencyCode>
  <cac:AccountingSupplierParty>
    <!-- Seller data -->
  </cac:AccountingSupplierParty>
</Invoice>

The correction here is to add a cbc:UUID line with a generated unique identifier value, then regenerate and sign the document. More importantly, fix the source that let the line drop out, rather than adding the line manually once, otherwise the error will recur in the next invoice. And to go deeper on the position of each element within the document tree, see the page Invoice Header in XML.

Why header fields drop out in the first place

A developer rarely deletes a field from the header on purpose. The field drops out for recurring automated reasons, and knowing them points your diagnosis straight to the source:

• An empty value instead of absence. The field exists in the template but its value is empty, because the source feeding it returned a null value. Validation treats an empty field the same as a missing one.
• Conditional UUID generation that did not run. Some systems generate the unique identifier in a later step or under a certain condition, so if the condition fails the invoice comes out with no UUID.
• Issue time not populated. Many templates populate the date IssueDate and forget the time IssueTime, so the date passes and the time drops out.
• An incomplete or manually edited template. An XML template from which an element was deleted during a previous edit, or copied from an older template that does not contain all the fields the second phase mandates.
• Incomplete seller data in the setup. The entity did not complete its identity data in the system, so the seller block came out incomplete in the header.

The common denominator is that the source is configurational, not momentary. The field did not place itself suddenly; it went missing because an earlier stage in the production line did not fill it. This is why fixing a single invoice is not enough unless you address the source that produced the gap.

How to correct the invoice and resend it

The correction goes through three steps whose order may not be skipped. The most important point is that resending is not repeating the same file, but generating a new file after adding the field, because any change in the content changes the invoice hash.

The common mistake here is that the developer adds the missing field to the same rejected file and resends it. This does not work, because the already-signed invoice now has its hash tied to old content. Any change in the content, even adding a single character, requires regeneration and signing. Add the field at its source, regenerate the document, sign it with a CSID certificate, then send it. This order guarantees that the new invoice is sound both structurally and in signature together.

Note also that fixing the header may reveal a subsequent error that was masked. When the header is complete and passes, validation moves to the next layer, so an error in the business rules or the calculation may appear. This is progress, not a setback: every layer that passes brings you closer to acceptance, and you handle the errors layer by layer in the same order the platform inspects them.

How to tell 1017 apart from XML structure error 1013

What confuses people most is the difference between error code 1017 and error code 1013. Both occur at the structure layer, and both stop the invoice before calculation and signing, but their sources differ and their handling differs. Confusing them makes you look in the wrong place.

The practical rule: if validation accepts the document structure as a whole (you find XSD_ZATCA_VALID in the information messages) but rejects it for a missing field, you are dealing with 1017. But if it rejects the document at the schema level itself, you are dealing with 1013. The first is a problem of missing content in a sound structure, and the second is a problem of a broken structure. For full detail on the document structure, see the page XML errors in the e-invoice, and to understand the fields as they appear at the top of the document, see the page Invoice Header in XML.

Practical scenario: a store in Jeddah forgets the issue time

A retail store in Jeddah connected its point-of-sale system to the Fatoora platform through an in-house integration. Invoices pass smoothly throughout the day, then a batch of evening invoices starts getting rejected with code 1017. The team inspects the numbers and the tax and finds no fault, because the problem is not there at all.

On inspecting the header, it turns out the issue time field IssueTime comes out empty in the invoices issued after midnight, because the time function in the template relied on a field that resets when the day changes. The date IssueDate was always populated, but the time drops out in this edge case. The field exists in the template, but its value is empty, and validation treated it the same as a missing one.

The solution was not to fix a specific invoice, but to fix the time function in the template so it relies on a reliable timestamp independent of the day changing. After the correction, the rejected invoices were regenerated and signed anew, so they all passed. This embodies the rule: code 1017 almost always points to a systematic configurational fault, not to an individual slip in a single invoice.

Where code 1017 falls in the order of validation layers

The platform does not inspect the invoice all at once, but passes it through successive layers and stops at the first layer where it fails. Code 1017 falls in the first layer, the structure and format layer, specifically at the check of mandatory field completeness. This explains why you never see any message about calculation or signing alongside code 1017: validation has not reached them yet, because it stopped at the header barrier.

The practical benefit of understanding this order is that you handle the errors in the same sequence as the platform. When the header is complete and code 1017 disappears, validation moves to the next layer, so an error may appear in the business rules such as the line-item total not matching the grand total, or an error in the signing layer. The appearance of a new error after fixing the header is not a regression, but proof that you advanced a layer. To understand this category of structural validation errors as a whole and how they cascade, see the page Validation Errors.

This sequence leads to a useful diagnostic habit: do not try to fix everything all at once. Fix what the platform raised now, resend, and read the next response. Every cycle reveals the next layer, and brings you closer to a clean acceptance step by step.

What happens if you leave the error unresolved

Code 1017 is not a warning you can ignore, but an outright rejection. The invoice that carries it has not been approved, as if it were never legally issued. Ignoring the error means you are selling without an invoice approved by the Authority, and this exposes you to compliance consequences upon review.

More dangerous is that code 1017, when it recurs, almost always is a symptom of a systematic configurational fault, not an individual case. A single invoice with an incomplete header may be a coincidence, but a batch of them means the production line itself is producing incomplete invoices. Ignoring that silently accumulates unapproved invoices until you are surprised by the size of the problem all at once. Address the source early, as the cost multiplies the longer you delay.

How to prevent the error from recurring for good

Preventing code 1017 is far easier than chasing it after it occurs, and it rests on a single idea: do not let a mandatory field leave your system unless it is filled. Make this a rule in the production line, not a hope in the vigilance of the operator.

• Local validation before sending. Add a check that rejects any invoice before sending it to clearance if its header lacks any of the six fields. Catching the error at your end is far cheaper than catching it at the Authority.
• Unconditional UUID generation. Make generating the unique identifier a fixed part of creating every invoice, not a conditional step that may be skipped.
• A reliable timestamp for the time. Rely on a single reliable source for the issue date and time together, and test it on edge cases such as midnight and time-zone changes.
• Mandatory seller data in the setup. Make completing the entity’s identity a condition for enabling issuance, so no invoice leaves with an incomplete seller block.
• A single up-to-date XML template. Unify the template in a single source compliant with the second phase, and prevent manual copying from older templates.

These preventive layers turn code 1017 from a recurring error into a rare case you hardly ever see. More importantly, they move validation from the end of the journey at the Authority to its beginning inside your system, where the fix is faster and cheaper.

How Qoyod handles header fields for you

The fundamental difference between an integration you build and maintain yourself and a ready-made system like Qoyod is that Qoyod fills the header of every invoice from your structured data without you ever touching the XML file. Once you complete your entity’s data one time in the setup, Qoyod builds the seller block automatically at the top of every document.

• Automatic generation of the UUID and invoice ID. Qoyod generates the unique identifier for every invoice and orders the invoice numbers within the entity’s sequence, so neither of them drops out.
• A reliable issue date and time. Qoyod stamps every invoice with a precise timestamp at issuance, so the empty-time error that confuses manual integrations does not occur.
• Invoice type code per the classification. Qoyod sets the type code based on whether it is a tax or a simplified invoice, and directs it to clearance or reporting accordingly.
• UBL 2.1-compliant XML generation. Qoyod builds the full document compliant with the Authority’s specification, and manages the digital signature and CSID certificate automatically.

One task remains that no system does on your behalf: registering the CSID compliance identifier with the Authority one time when you start activation, and Qoyod guides you through it step by step. After that, the system handles the entire technical layer, so header errors like code 1017 shrink to a minimum.

Frequently asked questions

Which fields does code 1017 refer to in the header?
The six mandatory fields at the top of the document: the invoice ID, the unique identifier UUID, the issue date and time, the invoice type code, the currency code, and the seller data. The absence of any of them, or leaving it empty, produces the same code.

What is the difference between code 1017 and code 1013?
Code 1017 means a specific mandatory field is missing from a structurally sound header. Code 1013 means a fault in the document structure itself or a violation of the UBL 2.1 schema. The first is a problem of missing content in a sound structure, and the second is a problem of a broken structure.

Do I resend the rejected invoice as is after adding the field?
No. Any change in the content changes the invoice hash, so the document must be regenerated and signed with a CSID certificate anew before resending. Add the field, regenerate, then send.

Why does the IssueTime field drop out so often while the IssueDate passes?
Because many templates populate the date and forget the time, or rely for the time on a source that resets when the day changes. Unify the source of the date and time together and test it on edge cases such as midnight.

Does the invoice appear in the clearance layer after code 1017?
No. Code 1017 stops the invoice in the structural validation layer before clearance, so the value comes out as clearanceStatus with a value of NOT_CLEARED. The invoice will not reach clearance until its header is complete.

Does Qoyod exempt me from dealing with code 1017?
Qoyod fills the mandatory header fields automatically from your structured data, so it shrinks header errors to a minimum. It remains for you to register the CSID compliance identifier with the Authority one time at the start, and Qoyod guides you through it.