UUID Errors in E-Invoicing

You are building your integration with the Fatoora platform and testing your first invoice, when it bounces back rejected over one small field: the UUID unique identifier. This field is among the most confusing sources of error in e-invoicing, because it looks like a minor technical detail while a single mistake in it is enough to reject the entire invoice. This page is a specialist guide to «UUID errors» alone, within Qoyod’s e-invoicing system.

Before we begin, if you want to understand the UUID field itself (its definition, format, and place in the XML), its reference is the page The UUID unique identifier in the e-invoice. Here we assume you already know the field, and we focus exclusively on the errors it causes: how they appear, their root cause, and how to fix them. For an overview of the rest of the system’s error categories, see the ZATCA e-invoicing error guide.

The target audience here is the developer or technical integration lead building a connection between an accounting system and the Fatoora platform. That is why you will find real JSON examples of the Authority’s responses, with each error explained as a problem statement followed by a solution. English technical tokens such as cbc:UUID and validationResults stay as they are, because they are actual field names in the API.

Why a wrong UUID rejects the invoice entirely

The UUID is a mandatory field in every e-invoice in Phase Two. It is a globally unique fingerprint that distinguishes each invoice document from any other invoice in any system in the world. The Authority relies on it to identify the document during clearance and reporting, and to prevent duplicate invoices in its register.

Because the field is mandatory and format-constrained, it accepts no half measures. The value must be present, correctly formatted, and unique — or the invoice is rejected. There is no «warning» state for most UUID errors, but a direct rejection that sets status to ERROR. That is why understanding and testing this field early saves you whole batches of rejected invoices at once.

Practical UUID errors fall into five recurring patterns. All of them appear at the structure or business-rules layer, and all are preventable with correct programming of the identifier-generation logic. We present each pattern as a problem statement, then its root cause, then the solution.

Before the details, one essential point deserves clarifying. Most new integration developers treat the UUID as if it were an ordinary serial number, and so fall into the same errors. But the UUID is not a number you choose; it is a random value generated by a specific standard to be globally unique with no coordination between systems. Understanding this difference alone prevents four of the five patterns, because the root of most of them is treating the random identifier as a serial number.

The timing of generating the value is no less important than the way it is generated. The value must be generated at the moment each invoice document is created — not before, not after. Generating it early (when preparing a template, for example) opens the door to duplication, and deferring it may produce an empty field. The correct time to generate is the point of document creation itself, once per document.

Detailing the five error patterns

Each of the five patterns has a different signature in the Authority’s response, and a different root cause in your system’s logic. Confusing them wastes diagnosis time, because the solution differs radically from one pattern to another.

Error one: UUID duplicated between two invoices

Problem statement. You send two or more invoices; the first is accepted and the second is rejected with a message indicating the identifier was previously used. status returns ERROR, and the category field points to document duplication or identifier conflict.

This is an example of a rejection response due to a duplicate UUID. Notice that the code explicitly indicates the identifier is not unique:

{
  "validationResults": {
    "status": "ERROR",
    "errorMessages": [
      {
        "type": "ERROR",
        "code": "DUPLICATE_UUID",
        "category": "DUPLICATE_DOCUMENT",
        "message": "Invoice UUID already exists for this taxpayer"
      }
    ],
    "warningMessages": []
  }
}

Root cause. Your system generates the same value for two different documents. The most common cause is generating the UUID once and storing it fixed in a template, or copying an old invoice along with its identifier instead of generating a new one, or a flaw in the random-number generator that makes it repeat values.

Solution. Generate a new UUID value at the moment each invoice is created, using a standard version-four generator. Do not derive the value from the invoice number, the date, or any repeatable data. Store every generated identifier in a table, and verify before sending that it has not been used before in your system.

To verify the root of the problem in practice, inspect when your code calls the generation function. If you find it called on template load or at the start of the user session, that is the flaw: the value is generated once and reused on every invoice. Move the call inside the invoice-creation function itself, so that each document maps to an independent generation call. Also add a unique constraint on the identifier column in your database, so this constraint prevents you from saving a duplicate identifier even if it slips past the application logic.

Error two: invalid UUID format

Problem statement. The invoice is rejected with a message indicating the identifier value does not match the required format. This usually appears at the structure layer, because the UBL schema checks the field’s pattern before looking at its content.

The correct format is the 8-4-4-4-12 pattern of hexadecimal characters, with a total length of 36 characters including four hyphens. Any deviation from this pattern rejects the value. This is an example of a rejection due to a wrong format:

{
  "validationResults": {
    "status": "ERROR",
    "errorMessages": [
      {
        "type": "ERROR",
        "code": "INVALID_UUID_FORMAT",
        "category": "XML_SCHEMA",
        "message": "cbc:UUID value does not match the required UUID pattern"
      }
    ],
    "warningMessages": []
  }
}

Root cause. The value sent is not a valid UUID. Common examples: wrong length (fewer or more than 36 characters), or characters outside the allowed set (letters other than a to f, or symbols), or dropping the hyphens, or using an identifier that is not version four. Version four is distinguished by the digit 4 at the start of the third group, and a value of 8, 9, a, or b at the start of the fourth group.

Solution. Use a standard function to generate a UUID v4 from your language’s library, and do not build the value by hand. Validate the value before sending with a regular expression that matches the v4 format exactly, so it catches any deviation before it reaches the Authority. Avoid any uppercase or lowercase conversion that might change the value unintentionally.

Also pay attention to the stage of moving the value between your system’s layers. Sometimes the identifier is generated correctly, then corrupted while being stored in or read from the database, so a digit is truncated or a separator is dropped. That is why you should test the value specifically at the point where it is built into the XML, not only when it is generated. The value that actually comes out in the cbc:UUID field is what the Authority checks, and it is what must match the pattern exactly.

Error three: cbc:UUID field missing entirely

Problem statement. The invoice is rejected at the structure layer with a message indicating a mandatory element is not present. This happens when the document leaves your system with no UUID field at all, or with an empty value.

Because UUID is a mandatory field in the UBL schema, its absence halts validation before any other value is examined. The message refers to the cbc:UUID element by name:

{
  "validationResults": {
    "status": "ERROR",
    "errorMessages": [
      {
        "type": "ERROR",
        "code": "XSD_SCHEMA_INVALID",
        "category": "XML_SCHEMA",
        "message": "Element 'cbc:UUID' is required but was not found"
      }
    ],
    "warningMessages": []
  }
}

Root cause. The XML-building logic in your system does not add the cbc:UUID element, or adds it with an empty value when identifier generation fails silently. Sometimes the cause is a conditional branch that skips identifier generation in a particular case, such as credit notes or amended invoices.

Solution. Make UUID generation a mandatory step in every invoice-creation path, with no exception for any document type. Verify before generating the XML that the identifier value is present and not empty, and stop the send if it is not, rather than sending an incomplete document. Treat a missing identifier as a programming error that warrants halting, not as a case to pass through silently.

Error four: UUID reuse on resend

Problem statement. This is the most deceptive of the UUID errors. An invoice fails for any reason, you correct it and resend it, and this time it is rejected with a duplicate-identifier error even though the «content» changed. The reason is that you reused the old identifier instead of generating a new one.

The essential rule here: every new send of a new invoice document requires a new UUID. Even if the invoice is «the same» in your view, correcting its lines and rebuilding it produces a new document that deserves a new identifier. The response returns with the same duplication code:

{
  "validationResults": {
    "status": "ERROR",
    "errorMessages": [
      {
        "type": "ERROR",
        "code": "DUPLICATE_UUID",
        "category": "DUPLICATE_DOCUMENT",
        "message": "Submitted UUID was already used in a previous submission"
      }
    ],
    "warningMessages": []
  }
}

Root cause. Your system links the UUID to the invoice record in your database, so it retrieves the old value on resend instead of generating a new one. This confusion between «the invoice’s identity in your system» and «the identifier of the document sent to the Authority» is the root of the problem.

Here a subtle distinction from idempotency logic appears. Idempotency uses a fixed identifier to avoid creating two invoices when there is an ambiguous interruption during «the same attempt». But resending a corrected document is a new attempt for a new document, and so requires a new identifier. Distinguishing between the two cases is essential.

Solution. Generate a new UUID on every rebuild of the document, and keep the human-readable invoice number (cbc:ID) as it is if you need to track it internally. Separate clearly between the invoice’s identity in your system (which may stay fixed) and the identifier of the sent document (which changes with every new send). If you are handling a temporary interruption of the same attempt, that is an idempotency case, managed with retry logic rather than by rebuilding the document.

Error five: confusing the UUID with the invoice number or ICV

Problem statement. Scattered errors that are hard to explain: rejected values in a field, unexpected duplications, or invoices that are accepted but with broken ordering or tracking. The hidden cause is often putting the wrong value in the wrong field, because the system contains three identifiers that are easy to confuse.

The e-invoice carries three distinct identifiers, each with its own role and format:

• The UUID unique identifier (cbc:UUID): a globally random, unique fingerprint for each document, in the 8-4-4-4-12 format, changing with every invoice and not sequential.
• The human-readable invoice number (cbc:ID): the sequential commercial number you see on the printed invoice, such as INV-1024, set by your system according to your internal numbering.
• The ICV sequential counter: a counter that increments by one over the previous invoice, proving the invoices are sequential without gaps. It is detailed on the page The ICV invoice counter in the e-invoice.

The common confusion is putting the human-readable invoice number in the UUID field, or trying to make the UUID sequential like the ICV. Both actions are wrong. The UUID is random, not sequential, unique to each document, and carries no commercial meaning.

Solution. Set an explicit mapping in your code of each value to its field: the randomly generated UUID to cbc:UUID, your sequential invoice number to cbc:ID, and the incrementing counter to ICV. Review the field mapping once carefully, because a mapping error here recurs in every invoice until you fix the root.

A practical way to detect this confusion: print the three fields side by side for ten consecutive invoices. If you find the cbc:UUID value increasing steadily or matching the invoice number, you are confusing them. A correct UUID looks entirely random and has no relation to the invoice number or its order. The ICV counter, by contrast, must increase by one between each invoice and the next. This quick visual check catches most mapping errors before any invoice reaches the Authority.

A step-by-step methodology to diagnose a UUID error

When a response returns with an identifier-related error, follow this sequence instead of guessing. This methodology pinpoints the pattern precisely and directs you to its appropriate solution.

1. Read code and category. A code like DUPLICATE_UUID points you to the duplication pattern, INVALID_UUID_FORMAT to the format pattern, and a missing element to the missing-field pattern.
2. Inspect the value actually sent. Print the cbc:UUID value that came out of your system, and check its length and format visually before any deeper analysis.
3. Distinguish duplication from resend. If the error is a duplication, ask: are these two different invoices with one identifier, or a resend of a document you corrected? The solution differs between the two cases.
4. Confirm the field mapping. Check that you did not put the invoice number or ICV in the UUID field. This error explains many ambiguous symptoms.
5. Fix the root, not the invoice. Fix the generation or mapping logic in your system, so the error disappears from every invoice, not just one.

Log every recurring UUID error with its code and date. A single code recurring means a flaw in your system’s logic, not in a particular invoice, and treating the root saves you rejected batches in the future.

How Qoyod helps you avoid UUID errors

Qoyod generates the UUID unique identifier on your behalf in every invoice, in version four and the correct format, so you do not need to write generation logic or manage field mapping by hand. This removes the five error patterns at the source.

• Generates a unique UUID for each invoice automatically. Qoyod generates a new, correctly formatted identifier when each document is created, so the format error and the missing-field error are eliminated.
• Prevents identifier duplication. Qoyod ensures each invoice carries its own identifier, and generates a new identifier when any document is rebuilt, so it avoids the duplication error and the reuse error.
• Separates the three identifiers automatically. Qoyod places each value in its correct field: the UUID in cbc:UUID, the invoice number in cbc:ID, and the counter in ICV, so the confusion error is eliminated.
• Generates UBL 2.1-compliant XML. Qoyod builds the document per the Phase Two specification, so all identifier fields come out in their correct positions with no intervention from you.

You still need to register the compliance stamp identifier (CSID) with the Authority once at the start, and Qoyod guides you through this step. Qoyod’s technical support is available 24 hours a day, seven days a week to help you if you face any error message you do not understand.

Common UUID errors worth early attention

Some UUID details confuse those starting integration. Knowing them in advance shortens the path and prevents the rejection of whole batches.

Generating the identifier once and storing it in a template. The most common cause of duplication. If you generate the value when preparing the template rather than when creating each invoice, all your invoices come out with the same identifier. Always generate at the moment of creation.

Deriving the UUID from repeatable data. Building the identifier from the invoice number, the date, or the customer name breaks its randomness and opens the door to matching. Use only a standard random version-four generator.

Changing letter case. Converting the UUID value to uppercase or lowercase after generating it may cause a mismatch in some comparison paths. Pass the value exactly as the generator produced it, without any modification.

Reusing the identifier of a failed invoice. When correcting a rejected invoice and resending it, generate a new identifier. Keeping the old one because it is «the same invoice» is the root of the reuse error.

From fixing the invoice to fixing the generation logic

The difference between a team chasing UUID errors invoice by invoice and a team issuing its invoices calmly is not in the number of errors, but in where the fix happens. A UUID error is rarely a single-invoice problem; it is a symptom of a flaw in the identifier-generation logic that affects every invoice passing through it.

A duplication code means your generator repeats values or stores them fixed. A format code means you are not using a standard version-four generator. A missing field means the XML-building path skips the field in some case. Treat the root, and the dependent errors disappear at once.

Systems that handle identifier generation automatically, such as Qoyod, remove these patterns at the base, so your error log shrinks to rare cases. But understanding the structure remains useful, because it makes you able to read any identifier-related error message and identify its pattern instantly, whether you built the integration yourself or relied on a ready-made system.

When a UUID error appears in testing and when in production

The timing of a UUID error’s appearance reveals a lot about its cause. Some patterns appear immediately in the first test, and some stay dormant until invoices accumulate in production. Knowing where to expect each pattern shortens diagnosis time.

The format error and the missing-field error usually appear in the first test invoice, because they are a fixed structural flaw that needs no accumulation. If you pass the first invoice successfully, your format and field are most likely sound. So testing one invoice is enough to be reassured about these two patterns.

The duplication error and the reuse error, however, appear later, because they need at least a second invoice. Many systems succeed in testing with a single invoice, then collapse in production on the second invoice or on the first resend. So always test by issuing at least two consecutive invoices, then try resending a corrected invoice, before you trust that the generation logic is sound.

The identifier-confusion error is the most insidious of all, because it may not cause an immediate rejection, but a tracking imbalance that appears on review or audit. So do not settle for the invoice being accepted; verify that each value landed in its correct field as it appears in the XML actually sent.

Frequently asked questions

Why is my invoice rejected with a duplicate-UUID error even though it is a new invoice?

Usually because your system generates the identifier once and stores it fixed in a template, or copies an old invoice along with its identifier. Generate a new UUID value at the moment each invoice is created using a standard version-four generator, and verify before sending that it has not been used before.

What is the correct format for a UUID value and how do I validate it?

The format is the 8-4-4-4-12 pattern of hexadecimal characters, 36 characters long including four hyphens, with the digit 4 at the start of the third group. Validate the value before sending with a regular expression that matches the version-four format, catching any deviation before it reaches the Authority.

Should I use the same UUID when resending an invoice I corrected?

No. Every rebuild of an invoice document requires a new UUID, even if it is «the same invoice» in your view. Keeping the old identifier produces a duplication error. Generate a new identifier and keep the human-readable invoice number (cbc:ID) if you need to track it internally.

What is the difference between the UUID, the invoice number, and the ICV counter?

The UUID is a random, unique fingerprint for each document in the cbc:UUID field and is not sequential. The invoice number (cbc:ID) is the human-readable commercial number you set per your numbering. The ICV is a counter that increments by one, proving the invoices are sequential. Each value in its field; confusing them causes ambiguous errors.

Why is my invoice rejected with a message that the cbc:UUID field is missing?

Because the XML-building logic in your system does not add the field or adds it empty. Make UUID generation a mandatory step in every invoice-creation path with no exception, verify before generating the XML that the value is present and not empty, and stop the send if it is not.

Does Qoyod relieve me of dealing with UUID errors?

Qoyod generates the UUID unique identifier, unique for each invoice, in version four, places it in its correct field, and generates a new identifier when any document is rebuilt. This removes the UUID error patterns at the source. You still need to register the compliance identifier (CSID) with the Authority once at the start.