Xero Troubleshooting

Error codes, preflight failures, and recovery steps for common Xero sync issues.

Prerequisites checklist

Before troubleshooting individual errors, verify the foundation is complete:

• Xero is connected (Configuration → Integrations shows Connected)
• Tax Rates synced at least once
• All Xero tax types mapped to a local tax code (no Unmapped or Needs Review rows)
• Contacts synced at least once
• Items synced at least once
• Sync Invoices toggle is enabled

If any of these are incomplete, complete them in order before retrying. See Sync Setup for the step-by-step guide.

Invoice push errors

XERO_EXPORT_CONTACT_MAPPING_REQUIRED

Meaning: The customer on this invoice does not have a linked Xero contact.

Fix:

1. Go to Configuration → Integrations → Contact Mapping.
2. Find the customer and assign the matching Xero contact.
3. If the contact doesn't exist in Xero yet, create it in Xero first, then re-run Sync Contacts.
4. Retry the invoice push.

XERO_EXPORT_ITEM_MAPPING_REQUIRED

Meaning: One or more invoice lines contain a product that has no linked Xero item code.

Fix:

1. Go to Configuration → Integrations → Item Mapping.
2. Find the unmapped product and assign the matching Xero item.
3. If the item doesn't exist in Xero, create it in Xero first, then re-run Sync Items.
4. Retry the invoice push.

XERO_EXPORT_TAX_MAPPING_REQUIRED

Meaning: One or more invoice lines use a tax code that has no mapping to a Xero tax type.

Fix:

1. Go to Configuration → Integrations → Tax Rate Mapping.
2. Map all rows showing Unmapped or Needs Review.
3. Re-run Sync Items so products pick up the updated tax mapping.
4. Retry the invoice push.

FREIGHT_NOT_FINALIZED_FOR_XERO_EXPORT

Meaning: The invoice has freight set to TBC (manual / to be confirmed). Xero requires a final freight amount before the invoice can be exported.

Fix:

1. Open the invoice detail.
2. Update the freight charge to a fixed amount.
3. Confirm the invoice.
4. Retry the invoice push.

BATCH_LIMIT_EXCEEDED

Meaning: You selected more than 50 invoices in a single batch push request.

Fix: Split the selection into batches of 50 or fewer and push each batch separately.

NO_ELIGIBLE_INVOICES

Meaning: All selected invoices are either already linked or blocked by a prerequisite error.

Fix: Review the blocked invoices individually for specific error codes.

Sync setup errors

Tax rate sync is blocked / Items sync won't start

Cause: Tax rate mapping is incomplete. Items sync requires all Xero tax types to be mapped.

Fix:

1. Go to Configuration → Integrations → Tax Rate Mapping.
2. Map every row that shows Unmapped or Needs Review.
3. Re-run Sync Tax Rates if the list looks incomplete.
4. Once all rows are mapped, Sync Items will become available.

Sync button is disabled / greyed out

Cause: A cooldown is active for that scope.

Fix: Wait for the countdown to reach zero. Cooldown periods:

Sync shows running but never completes

Cause: The background job may be queued or the async worker may be processing other tasks.

Fix:

1. Wait 2–3 minutes and refresh the page.
2. If still running after 5 minutes, check Recent Sync Logs in Configuration → Integrations for any error entries.
3. If logs show a rate limit error (HTTP 429 from Xero), the system retries automatically up to 5 times with backoff. Allow additional time.

Invoice pull issues

Variance badge appears after refresh

Meaning: The Xero version of the invoice differs from the local version.

Action: Open the invoice detail to review the differences. Variance is shown in read-only mode — update the local record manually if needed.

Invoice pull returns no updates

Possible causes:

• No linked invoices have been modified since the last watermark.
• The selected time window is too narrow.

Fix: Try a wider time window (e.g. Last 7 days) when triggering the pull from the Invoices list.

INVOICE_ALREADY_LINKED

Meaning: The invoice was already pushed to Xero previously. It cannot be pushed again.

Fix: Use Refresh Xero Status (invoice pull) to update the status of the existing linked invoice instead.

Connection issues

Xero shows as disconnected after reconnecting

Cause: The OAuth token may have expired or been revoked in Xero.

Fix:

1. Go to Configuration → Integrations.
2. Click Disconnect to clear the old tokens.
3. Click Connect Xero and complete the OAuth flow again.
4. Re-run all sync modules if needed (existing mapping records are preserved).

Related

• Xero Integration Overview
• Sync Setup — Tax Rates, Contacts & Items
• Invoice Push
• Invoice Pull & Status Refresh