Xero Error Messages on export from Lightyear to Xero

Troubleshooting Xero Error Messages

Lightyear has a ton of built in validation checks to ensure the data is correct in Lightyear before trying to send the Bill and information to Xero.  However, there are occasions when the  Export fails and Lightyear displays the reason for the error - you will see a warning message with information like the below, directing you to the document's Activity History.

Here are some of the most common errors Lightyear receives, presented in [brackets]:


Failed to export invoice [An existing contact could not be found using the specified contact details. The contact name field is required to create a new contact.]

Lightyear is trying to write Purchase Data to a Contact that doesn't exist in Xero. First you want to try to reimport the Contact from Xero following these steps:

1. As an admin, navigate to Settings > Accountancy > Supplier Cards.
2. Select the Contact or Supplier from the list, and delete it using the Trash Icon (don't worry, we're going to re-import this from Xero, if it exists)
3. Click 'Import all'

If the Supplier or Contact appears in the list, great... assign this as the 'Accounting Supplier' and you're good to export.

If not, create a new 'Accounting Supplier' in Lightyear to push to Xero will successfully export your document too.

Failed to export invoice [The contact with the specified contact details has been archived. The contact must be un-archived before creating new invoices or credit notes.]

This error is being received as the supplier has been archived in Xero and must be restored before the export will be successful. This must be done within Xero. 

In Xero, go to your contacts menu and select All Contacts. Next, select Archived. This will present a list of all archived suppliers within Xero. Select the contact to open their details and click restore. Click restore to confirm. 

Failed to export invoice [Bill failed to export [Invalid UUID string: XXXXXXX]. Please contact technical support.]

Please check that an Accounting Supplier card is linked to your Lightyear Supplier profile.

Head over to Suppliers > Select the supplier > check that an Accounting Supplier is selected.

If you can't find your supplier card here, you can create the Supplier Card within Lightyear (check that you don't have one existing in Xero first to avoid duplicates).

Update your settings and try to export again.

Coding: GL Codes, Tax Rates

Xero Export failed: Tax rate must be Active

In markets outside of the US, UK, Australia and New Zealand, Xero has a series of default tax rates that are supplied "out of the box".  One of these is "Tax on Purchases" which has a invisible label behind it (something you and I don't see) called "INPUT".  

You, as a user, can set that tax rate from the default 0% to the tax rate of your jurisdiction.  Lets for the sake of argument say you are a South African company, therefore you should set it to 14%.

When Lightyear sends data to Xero, the way we tell Xero that an that an expense carries tax is by telling Xero that the value needs to have "INPUT" applied to it.  Xero then knows that "INPUT" relates to Tax on Purchases, and that Tax on Purchases has been set by you to be 14%.
But, Xero allows you to add or delete tax rates.  

If you delete a tax rates such as "Tax on Purchases", you cannot reinstate it.  From a Xero perspective it is now permanently inactive.  If you delete it, you also delete 'INPUT" from Xero's records.

If Lightyear sends to Xero that an expense needs to have INPUT applied to it, but you have deleted INPUT from Xero's memory, the import will fail.  In effect Xero says "I have no idea what INPUT means".

Xero Export failed: Account Code 'XXX' is not a valid code for this document

The Account Code/GL Code you have chosen for the bill cannot be used with purchases.  When Lightyear sends bills through to Xero, Xero expects you to assign an Account Code that relates to purchases.  i.e. expense code vs income code.

From the Signed Off tab, click MORE > Return to Review to send the bill back to the previous tab where you can assign a and expense Account Code to it.  Then sign it off again, then try to export again.

Failed to export invoice: The Tax Type code 'OUTPUT2' cannot be used with account code 'XXX'

The Tax Code you've chosen for the bill cannot be used with purchases. When Lightyear sends bills through to Xero, Xero expects you to assign a Tax Code that relates to purchases. i.e. expense code vs income code.

From the Signed Off tab, click MORE > Return to Review to send the bill back to the previous tab where you can assign an expense Tax Code to it.  Then sign it off again, then try to export again. Be sure to check every line as it only needs to be assigned to one line for this error to appear.

Account Settings

Xero Export failed: The document date cannot be before the period lock date, currently set at DD-MM-YYYY

You are trying to export bills with a date that is in a date range of a locked out period within Xero.  

In Xero - unlock the date period and the export from Lightyear will now work.

If reporting is already done for this period, some customers will choose to change the invoice's date instead, but this is a personal choice and both may have negative consequences.

Error: 'Organisation is not subscribed to currency'

Xero is sending this error message because your Xero account/organisation is not sest up to handle foreign currency. 

You have 2 options to resolve exporting this invoice and which one you choose is dependent on whether you are likely to use foreign currencies regularly;
  1. Subscribe to foreign currency within Xero, then select that specific currency for use in Xero. THis link below explains that you'oll need to start a Business Edition pricing plan with multi-currency, or a trial organisation, to add transactions in different currencies. Only the Subscriber for your organisation can change pricing plans. See https://help.xero.com/au/CurrencySettings
  2. You can change the currency on the invoice from the Review tab or Approval tab, to your local currency - but make sure you edit the price as well after you convert the currency

Line Items

Failed to Export Invoice [The line total [xxx] does not match the expected line total [xxx]. The total for this document must be greater than or equal to zero.]

You have manually edited an invoice, that's using a regular service/line item map, to be a credit note, and Lightyear is expecting the totals to be a positive number, or vice versa.

Send the invoice back to processing and manually edit to show the expected values, or search for a credit note map. If none are available, request a new credit note map.

Error: Item code 'XXX' is not valid

A Product Code needs to firstly exist within Xero in order to be able to export the Product Codes to Xero otherwise, the whole bill will be rejected upon export.

If this is the case, you will see the details in the Activity log listing those Products that need to be added.

See below for example.

To add new products into Xero, Head over to 1. Business > 2. Products & Services to see your product listing

You can choose to add a new item individually via 3. + New Item OR you can 4. Import products in bulk 


    Check out release notes for Q3 2021

     June  July  August 

      • Related Articles

      • Troubleshooting MYOB Error Messages

        [[BusinessEvent_DateOccurred_InLockPeriod; DateOccurred:(PurchaseEvent); BusinessEvent_DateOccurred_InLockPeriod; InventoryDateOccurred:(PurchaseEvent)]] Translation: Locked Period in MYOB If you are trying to export to a locked period, you will be ...
      • Error Messages Returned from accountsIQ Upon Export

        Lightyear has a ton of built in validation checks to ensure the data is correct in Lightyear before trying to send the bill and information to accountsIQ. However, there are occasions when the export fails and Lightyear displays the reason for the ...
      • Exporting from Lightyear to Xero

        From the Signed Off tab in Lightyear,  choose which invoices to export by selecting or deselecting under the tickbox column or individuals, then click the Export to Xero button.   At the end of the export process, you will get a confirmation on ...
      • Sending Product Codes to Xero

        Activating Product Codes to be sent Lightyear has always been able to extract line item details and we can now send these Product Codes to Xero as well! Activate this setting under Settings > Accounting Software > Accounting Software Settings > Send ...
      • Xero Integration Setup Guide

        Connecting to Xero Because Xero and Lightyear are both cloud-based, set-up and connectivity between the systems is seamless.  Here's how. From the Navigation Pane, head over to Settings > Accounting Software > select Xero > Connect.   You will be ...