When an export to Xero fails, the document moves to the Export Failed tab inside the folder. Open the document to see the exact error message returned by Xero, along with a Dismiss button.

The first step for any export error is the same: open the document, read the error, fix the underlying cause, click Dismiss, then export again. The sections below describe the most common errors grouped by what caused them.

👉 What does "Dismiss" do?

Dismiss clears the error from the document so you can try to export again. It does not fix the cause - if you dismiss without fixing what made the export fail, the next export attempt will fail the same way.

These errors mean that the link between Datamolino and Xero is not currently usable - either the connection has expired or the Xero user account does not have the right permissions.

👉 "Forbidden access. If the issue persists please reconnect your folder to Xero"

This usually means the connection between Datamolino and Xero has expired. To fix it, disconnect and reconnect the folder:

👉 Forbidden access keeps coming back after I reconnect. What now?

If the error returns even after disconnecting, reconnecting, and dismissing, the cause is usually the access rights of the Xero user that authorised the connection. The error is then tied to the Approval status you are trying to export with:

The rule of thumb for Xero permissions: if you want to export documents with Awaiting Approval or Awaiting Payment status from Datamolino, your Xero user must be able to move documents into that status in Xero itself.

Learn more about refreshing your accounting software connection and Xero export statuses.

👉 "Contact is mandatory"

The supplier name extracted from the invoice does not match any contact in Xero - Datamolino does not have a pairing between the supplier and a Xero contact, so the export cannot go through.

To fix it, open the document, click into the Contact field, and either:

Once you pair a contact with a supplier name, Datamolino remembers the selection - the next document from the same supplier will use the same Xero contact automatically. New contacts are only created in Xero when you click on Add Contact.

👉 The contact exists in Xero but it still says "Contact is mandatory". Why?

The contact must be active in Xero. Archived contacts are not used for export. Reactivate the contact in Xero, refresh the connection on the folder so Datamolino picks up the change, and re-pair the supplier with the contact.

These errors happen when Datamolino tries to export or update a document that is past the Draft stage in Xero. Only documents that are still in un-approved in Xero can be re-exported from Datamolino.

👉 "This invoice is already in Xero and cannot be modified. It is either 'approved' (awaiting payment) or it has been 'voided' in Xero."

The document was exported previously and has since been approved or voided in Xero. Datamolino does not overwrite approved or voided invoices - this is a safeguard against duplicates and against corrupting data that is already in your ledger.

To fix it:

👉 "The item exists in Xero with status different than draft"

This is the same situation seen from the other direction. You exported the document to Xero earlier with status Draft, the document was then advanced to Awaiting Payment, or Paid in Xero, and you are now trying to re-export. Datamolino can only re-export documents that are still in Draft or Awaiting approval.

If you still need to re-export, delete the document in Xero, delete it in Datamolino, and re-upload to Datamolino. The new document can be exported as Draft and edited freely.

👉 "Sales invoices error - unique number" (the document number is already used in Xero)

Xero requires that each sales invoice has a unique number. The export fails because a sales invoice with the same number already exists in your Xero organisation.

You can edit the invoice number in Datamolino and export again - for example, change INV0041 to INV0041a. Before you do, check why two different invoices ended up with the same number in your records - it usually points to a numbering gap that should be fixed in your billing process.

👉 "An existing Invoice with the specified InvoiceID could not be found"

This usually happens in one of two situations:

To fix it:

Moving a document between folders before it has been exported (status Ready) does not cause this error - only previously-exported documents are affected.

👉 "At least one Line item is mandatory!"

You switched the document to the Line items view but no line items were captured or added. Xero will not accept a document with zero lines on it, so the export is blocked until a line exists.

You have two options:

👉 "Account code 'xxxx' is not a valid code for this document"

Xero is rejecting the export because the selected ledger account isn't supported for this document type (e.g. a sales-only account assigned to a purchase invoice).

To fix this, pick one of the two options below:

Option 1 — Change the account in Datamolino

Option 2 — Fix the account settings in Xero

👉 "The TaxType code '....' cannot be used with account code '####'"

The tax code does not match the type of ledger account on the line - for example, a sales tax code combined with an expense (purchase) ledger account. The error message includes the numerical code of the ledger account so you can spot which line is wrong.

For example, exporting a bill that uses the 325 - Direct Expenses account with a 20% (VAT on Income) tax code returns: "The TaxType code 'OUTPUT2' cannot be used with account code '325'."

To fix it, change the tax code on the document to one that matches the ledger account type - in the example above, change to a VAT on Expenses tax code. If the ledger account is wrong rather than the tax code, update the account instead. Click Dismiss and export.

If the same combination keeps producing the error, check the tax code and the ledger account settings in Xero - they need to be aligned at the Xero side.

Tracking categories are optional in Xero, but a folder can be set up so that tracking categories are required on every document before export.

👉 The export fails because tracking categories are missing. What do I do?

Open the document and fill in every tracking category that appears on it. If your folder requires tracking categories, blank values block the export.

👉 Where is "tracking categories required" turned on?

This is a folder-level setting tied to the Xero organisation. If you cannot fill in a tracking category because the list is empty, the categories in Xero have probably changed since the last sync - run Refresh Xero Connection on the folder to pull the latest list.

Learn more about locking tracking categories in Xero and syncing your chart of accounts, tax codes, and tracking categories.

👉 "The document date cannot be before the period lock date, currently set at Day/Month/Year"

Xero has a period lock date set in your organisation settings. Any document with an issue date earlier than that lock date is rejected by Xero.

To fix it, either:

The lock date itself lives in Xero - Datamolino reports the date that Xero returned in the error message.

👉 "Bank account status invalid for payment creation"

This error appears on documents being exported as a bank transaction. It means the bank account selected on the document has been archived in Xero.

Open the bank account in Xero and check its status. If it should still be used, reactivate it. Then come back to Datamolino, select the correct active bank account on the document, dismiss the error, and export.

Some errors are not caused by anything wrong with the document - they happen because the connection between Datamolino and Xero hiccuped during the export.

👉 "Net readtimeout"

The Xero connection was too slow to respond during the export. Wait a short time and try exporting again - in most cases the second attempt succeeds.

👉 "Unknown response code 301 or 302"

A temporary issue on the connection between Datamolino and Xero. Try re-exporting after a few minutes.

👉 The error message is blank - I only see a date and time

A blank message is usually caused by a slow connection to Xero. Disconnect from Xero and connect back again.

👉 "Rate limit exceeded. Wait [number] hour(s) to retry."

Xero has a limit for the amount of information you can exchange per day. This error means that you have exceeded it.

You need to wait the number of hours specified in the error message before you attempt to export again.

When you're ready to retry, start small. Export 100–200 documents, wait around 5 minutes, then continue in batches. If documents don't appear in Xero immediately after export, wait before checking again — do not re-export. Duplicate requests will push you back into the limit.

To preserve the daily limit, avoid taking these actions unnecessarily:

👉 What is the checksum widget on the document?

Datamolino compares the captured invoice amounts with the amounts that will actually be sent to Xero - totals and tax amounts based on the tax code selected. If there is a difference, it is shown in the checksum widget inside the document view.

Exporting as Invoice total: This check is for visibility only - it does not block the export. You can:

👉 How does the tax setting affect this check?

The check interacts with the Xero tax setting on the folder:

Learn more about tax calculation in Xero: automatic vs. exact amount.

👉 I exported a document but cannot find it in Xero. Where do I look?

The quickest way is to click the Xero icon next to the document (or inside the document) in Datamolino - it opens the same document directly in Xero.

If the same error has affected many documents - typically after a Forbidden access incident or a long connection outage - you can dismiss the errors in bulk:

Datamolino translates the message returned by Xero, so the exact wording on screen depends on your account language and on Xero. If you see an error that is not described here, contact our support team at support@datamolino.com with the document open - we can read the full Xero response and help you fix it.