You can resolve most Xero export errors directly in Lightyear by identifying the error message and following the steps below.
When an export fails, Lightyear displays a warning banner on your page and directs you to the document's Activity History, where you'll find the specific error message.
Reconnect Lightyear to Xero
If you see the error 'Failed to export Bill [Forbidden - authentication unsuccessful]', the connection between Lightyear and Xero needs to be re-established.
Click Settings, then click Accountancy Software Settings.
Click Disconnect.
Click Connect, then follow the on-screen prompts and Xero Integration Setup Guide to reconnect.
Ensure the user performing the reconnection has admin permissions in both Lightyear and Xero.
📌 Note: If Xero shows the Lightyear connection as still active, follow the steps in 'How to disconnect from Lightyear via Xero. 📌 Note: Reconnecting does not delete or alter your company data in Xero or Lightyear. If concerned, take screenshots of your integration settings before reconnecting.
Fix a missing or unlinked supplier
If you see the error 'An existing contact could not be found using the specified contact details', Lightyear is trying to write purchase data to a contact that doesn't exist in Xero.
As an admin, click Settings, then click Accountancy, then click Supplier Cards.
Select the supplier from the list, then click the Trash icon to delete it. If there are duplicate supplier cards, delete all of them.
Click Import all.
If the supplier appears in the list, assign it as the Accounting Supplier, then retry the export.
If the supplier does not appear, create a new Accounting Supplier to export to Xero.
Ensure the user managing suppliers has the correct permissions in Lightyear, such as 'Admin' or 'Processing'.
If you see the error 'Bill failed to export [Invalid UUID string: XXXXXXX]', check that an accounting supplier card is linked to your Lightyear supplier profile.
Click Suppliers, then select the supplier.
Check that an Accounting Supplier is selected.
If no supplier card exists, create one in Lightyear, ensuring you don't already have one in Xero to avoid duplicates.
Click Save, then retry the export.
Restore an archived Xero contact
If you see the error 'The contact with the specified contact details has been archived', you need to restore the contact in Xero before the export will succeed.
In Xero, click Contacts, then click All Contacts.
Select Archived.
Select the contact from the list, then click Restore.
For more details, see Xero's article Archive or restore contacts.
Fix an invalid account code or tax code
If you see the error 'Account Code 'XXX' is not a valid code for this document', the account code assigned to the bill cannot be used with purchases.
From the Signed Off tab, click More, then click Return to Review.
Assign a valid expense account code to the bill.
Sign the bill off again, then retry the export.
If you see the error 'The Tax Type code 'OUTPUT2' cannot be used with account code 'XXX'', the tax code assigned cannot be used with purchases.
From the Signed Off tab, click More, then click Return to Review.
Assign a valid expense tax code to the bill.
Sign the bill off again, then retry the export.
Fix an inactive tax rate
If you see the error 'Tax rate must be Active', a default Xero tax rate has been deleted from your Xero account. You'll need to contact Xero support to resolve this, as deleted default tax rates cannot be recovered.
⚠️ Warning: Do not delete the default tax rates that Xero provides. If a rate such as 'Tax on Purchases' is deleted, it cannot be reinstated, and Xero will no longer recognise the associated tax code.
📌 Tip: Regularly review your tax rate settings in Xero to ensure all required rates are active and correctly configured.
Unlock a locked period in Xero
If you see the error 'The document date cannot be before the period lock date', you are trying to export a bill that falls within a locked period in Xero.
In Xero, unlock the relevant date period, then retry the export from Lightyear.
📌 Note: Some users choose to change the invoice date instead, but both options may have reporting consequences. Choose the option that best suits your needs.
Resolve a currency error
If you see the error 'Organisation is not subscribed to currency', your Xero account is not set up to handle foreign currency. You have two options:
To enable multi-currency in Xero, subscribe to a foreign currency within Xero and select the relevant currency. See Xero's Currently Setting guide for details on the pricing plan required.
To edit the invoice currency in Lightyear, change the currency on the invoice from the Review or Approval tab to your local currency, then update the price to reflect the correct value.
Resolve an invoice limit error
If you see the error 'You have reached the limit of invoices you can approve', your Xero subscription has reached its transaction quota. You'll need to upgrade your Xero subscription to continue exporting.
If unsure about the required plan, consult Xero support for guidance on selecting the appropriate subscription, to ensure it aligns with your organisation's transaction volume. After upgrading your subscription, resend the invoices to ensure they are processed successfully.
Fix a mismatched line total
If you see the error 'The line total [xxx] does not match the expected line total [xxx]', a manually edited invoice has a total that does not match what Lightyear expects.
Send the invoice back to Processing.
Manually edit the values to match the expected totals, or search for a credit note map.
If no credit note map is available, request a new one.