Skip to main content
This page covers Xero-specific export errors for invoicing, payroll, kilometres, and expenses. For errors related to missing accounting codes on payers, clients, or services, and for session and connection issues, see the general integration troubleshooting page.
For general Xero connection and accounting code errors, see Integration troubleshooting.

​
Invoicing errors

​
Error: Accounting code missing in Visualcare - try syncing again

Symptoms: The export status page shows “Accounting code missing in Visual Care Xero contacts - try syncing again” before you click Start Import. Cause: The client, payer, or service doesn’t have an accounting code selected in Visualcare, or the Xero sync is out of date. Fix:
  1. Go to Settings → Data Export
  2. Click all of the following sync buttons: Sync Contacts, Sync Invoice Items, Sync Employees, Sync Xero Pay Items, Sync Tax Rates
  3. Retry the export
  4. If the error persists, click Clear Xero Token, then click Authorise Xero to reconnect
  5. Repeat the sync buttons above, then retry the export

​
Error: Missing code in Xero

Symptoms: The export fails with “Missing code in Xero” for a service or kilometre entry. Cause: The inventory item for the service is not set up or is inactive in Xero, or the kilometre pay codes are not configured in Visualcare. Fix - for service-related missing code:
  1. Go to Maintenance → Services and open the affected service
  2. Check whether an Accounting Code is selected
  3. Log in to Xero and go to Business → Products and Services
  4. Make sure the relevant inventory item is set up and marked as active
Fix - for kilometre-related missing code:
  1. Go to Settings → Finance → Kilometre and confirm the kilometre codes are configured
  2. Open the relevant client agreement and check the Override setting
  3. If Override is ticked, make sure a kilometre code is selected. If the override isn’t needed, untick it

​
Error: FAIL Tracking option not found in Xero

Symptoms: The export fails with “FAIL Tracking option [value] in tracking category [name] not found in Xero”. Cause: A value in Visualcare doesn’t exactly match the corresponding tracking option in Xero. This is usually caused by a typo or extra space. Fix:
  1. Go to Settings → Data Export and scroll to the XERO section
  2. Note which field is selected under Link to Field
  3. Navigate to that field in Visualcare (for example, Area, Service Reference, Client Division)
  4. Check that the field’s value exactly matches the tracking option configured in Xero, including spelling and spacing

​
Error: To update fields on a paid invoice line item / Invoice not of valid status for modification

Symptoms: The export fails with one of these messages when exporting expenses or invoices. Cause: The next invoice number in Visualcare has already been used or paid in Xero, so Xero rejects the update. Fix:
  1. Go to Settings → Data Export → Accounting Software
  2. Update the Next Invoice Number to a value that hasn’t been used in Xero yet

​
Invoices exporting to the wrong accounting code

Symptoms: Invoices export to Xero but are assigned to the wrong contact or accounting code. Cause: Visualcare uses a hierarchy to determine which accounting code to apply. The order is: (1) Client Agreement Payer, (2) Client Payer, (3) Client Profile Accounting Code. If any of these are set incorrectly, invoices export to the wrong code. Fix:
  1. Go to Maintenance → Payers
  2. Search for the payer and open their profile
  3. Check the Accounting Code field and update it if needed
  4. Also check the client agreement to confirm the correct payer is selected there

​
Error: Xero Use GST not exporting correctly

Symptoms: Expenses export to Xero without GST, or GST is doubled. Cause: The Xero Use GST checkbox in Visualcare is conflicting with the GST rate set on the Xero inventory item. Fix:
  1. Go to Settings → Data Export
  2. Scroll down and untick the Xero Use GST checkbox
  3. Confirm that the GST rate is correctly configured on the inventory item in Xero

​
Error: No matching Xero contacts found

Symptoms: A “No matching Xero contacts found” browser error appears when exporting invoices to Xero. Fix:
  1. Re-sync your Xero contacts: go to Settings → Data Export and click Sync Contacts
  2. Check that each client, payer, and agreement has the correct Xero contact selected, and that names and spellings match what is recorded in Xero
  3. Review your invoice grouping settings in Settings → Data Export - incorrect grouping prevents the export matching to a single Xero contact. If invoice grouping is enabled, the recommended configuration is:
    • Group Invoice By 1: Payer
    • Group Invoice By 2: Client Code or Client Account Code

​
Payroll errors

​
Issue: Start Import stuck on “Checking XERO Data”

Symptoms: After clicking Start Import, the page stays on “Checking XERO Data” and doesn’t progress. Cause: The Xero integration has disconnected. Fix:
  1. Go to Settings → Data Export
  2. Click Clear Xero Token
  3. Click Authorise Xero and log in to Xero when prompted
  4. Try the import again

​
Error: Pay items and employees not showing after sync

Symptoms: After syncing, Xero pay items or employees don’t appear in the drop-down lists in Visualcare. Cause: A value in the KeyPay API Key field is causing the system to prioritise KeyPay over Xero, which suppresses the Xero sync. Fix:
  1. Go to Settings → Data Export → KeyPay Connection
  2. Clear any value in the API Key field
  3. Click the x to close the window and click Save
  4. Scroll down and click Sync Xero Pay Items and Sync Employees

​
Error: FAIL: Earnings Rate does not exist or is not valid for timesheets

Symptoms: The payroll export fails with this message. Cause: A pay item in Xero is not correctly configured. Common causes include the type of units not being set to Hours, the pay item being inactive, the item not being in the worker’s pay template, or an apostrophe in the pay item name. Fix:
  1. Log in to Xero and find the affected pay item
  2. Confirm the Type of Units is set to Hours and the item is active
  3. If using pay templates, make sure the pay item is added to the template for the affected worker
  4. Check for any apostrophes in the pay item name and remove them
  5. Go to Settings → Data Export in Visualcare and click the relevant Xero sync buttons
  6. Retry the export
This error is also covered in Integration troubleshooting with additional detail on pay item types.

​
Error: Employee doesn’t have a pay run calendar

Symptoms: The export fails with “Employee doesn’t have a pay run calendar”. Cause: The worker in Xero doesn’t have a pay calendar assigned. Fix:
  1. Log in to Xero and go to Payroll → Employees
  2. Open the affected worker
  3. Under the Employment tab, check the Pay Calendar field
  4. If it’s not set, click Edit, select the correct calendar, and save
  5. Retry the export

​
Error: No pay runs found

Symptoms: The export fails with “No pay runs found” when exporting kilometres. Cause: No pay run exists in Xero for the export period. Fix:
  1. Log in to Xero and create a pay run that covers the same date range as your export
  2. Save or finalise the pay run
  3. Retry the export in Visualcare

​
Error: No payslips found on payrun

Symptoms: The export fails with “No payslips found on payrun” when exporting kilometres or expenses. Cause: The timesheets haven’t been approved in Xero yet. Fix:
  1. Log in to Xero and go to Payroll → Pay employees
  2. Approve the timesheets for the relevant pay period
  3. Retry the export in Visualcare

​
Error: Provided period doesn’t correspond with a pay period

Symptoms: The export fails with “Provided period doesn’t correspond with a pay period”. Cause: The worker’s pay calendar in Xero doesn’t align with the export period selected in Visualcare. Fix:
  1. Log in to Xero and go to Payroll → Employees
  2. Open the affected worker and check the Pay Calendar under the Employment tab
  3. Update the calendar so it matches your intended export period
  4. If needed, also check Settings → Finance in Visualcare and confirm the Payroll Start Date and Payroll Cycle Days are correct
  5. Retry the export

​
Error: FAIL A validation exception occurred

Symptoms: The payroll or kilometre export fails with “FAIL A validation exception occurred”. Cause: The kilometre pay type in Visualcare doesn’t match how the KM pay codes are set up in Xero (Ordinary Time Earnings vs Reimbursement). Fix:
  1. Go to Settings → Finance → Kilometre in Visualcare and check how your KM pay codes are set up in Xero
  2. Go to Settings → Data Export → XERO → KM Pay Type
  3. Select pay item if the codes are Ordinary Time Earnings, or reimbursement if they’re reimbursements
  4. Retry the export

​
Kilometre export errors

​
Error: FAIL Unknown error during KM export

Symptoms: The KM export fails with “FAIL Unknown error”. Cause: The pay item assigned in Xero to the KM pay code has been modified or deleted. Fix:
  1. Go to Settings → Finance → Kilometre in Visualcare
  2. Confirm a valid Pay Code (KM) is selected
  3. Log in to Xero and verify the pay item exists and is correctly configured
  4. Retry the KM export

​
Warning: Super guarantee warning when exporting kilometres

Symptoms: A super guarantee warning appears during the KM export to Xero. Cause: The employee in Xero does not have super added to their pay template. Fix:
  1. Log in to Xero and go to Payroll → Employees
  2. Open the affected employee
  3. Add super to the employee’s pay template
  4. Save the employee record in Xero
  5. Retry the KM export in Visualcare

​
Error: TrackingItemID is required for each timesheet line

Symptoms: The export fails with “TrackingItemID is required for each timesheet line”. Cause: Timesheet tracking is enabled in Xero but not configured in Visualcare. Fix - if you don’t want timesheet tracking:
  • Log in to Xero and disable timesheet tracking
Fix - if you want to use timesheet tracking:
  • Contact support@visualcare.com.au and provide your Xero category name, the option values, and the Visualcare field you’d like mapped to it
  • Once the configuration is done, retry the export
If tracking is already configured but you’re still seeing this error, check that the tracking fields are filled in for the timesheets you’re trying to export.

​
Connection errors

​
Error: Authorise Xero Error Code 500

Symptoms: A “500” error appears when trying to authorise the Xero integration. Cause: A browser caching or session issue is interrupting the authentication process. Fix:
  1. Open your browser in Incognito Mode (or Private Browsing) and try authorising Xero again
  2. If the error persists, exit incognito mode, clear your browser cache and cookies, close and reopen your browser, then retry
  3. If the issue continues, try a different browser (for example, Chrome instead of Edge)

​
Error: FAIL undefined or Array no session during export

Symptoms: The export fails with “FAIL undefined” or “Array no session”. Cause: The connection between Visualcare and Xero has expired or is no longer valid. Fix:
  1. Go to Settings → Data Export
  2. Click the pink Clear Xero Token button
  3. Click Authorise Xero and log into your Xero account to reconnect
  4. Click all the sync buttons (for example, Sync Xero Pay Items, Sync Contacts)
  5. Retry the export

​
Error: Error sending to Xero [object Object]

Symptoms: The export fails with “Error sending to Xero. [object Object]” when sending a worker to Xero. Cause: Data in the worker profile contains formatting issues. The most common causes are spaces in the Tax File Number (TFN) field or invalid characters in the worker’s address. Fix:
  1. Open the Worker Profile in Visualcare
  2. Go to the Details tab and review the address for typos, extra symbols, or incorrect formatting
  3. Go to the Finance tab and locate the TFN field in the Worker Details column
  4. Remove any spaces or non-numeric characters from the TFN
  5. Click Save and retry the export

​
Sync issues

​
Issue: Xero sync not picking up new codes

Symptoms: After adding new contacts, employees, or inventory items in Xero, they don’t appear in Visualcare after syncing. Cause: An apostrophe in an item’s name in Xero prevents the sync from reading it correctly. Fix:
  1. Log in to Xero and review recently created or updated contacts, employees, or inventory items
  2. Remove any apostrophes from names
  3. Go to Settings → Data Export in Visualcare and click the relevant sync buttons again

​
Expense export errors

​
Error: Date cannot be changed on an invoice that has payments or credit notes allocated / invoice already exists

Symptoms: Expense exports to Xero fail with messages like “Date cannot be changed on an invoice that has payments or credit notes allocated to it”, “The status DRAFT cannot be applied”, or “The document cannot be edited as it is currently dated before the end of year lock date”. Cause: Either the expense has already been exported and the invoice is locked in Xero, or there’s an invoice number clash. Fix - if the invoice already exists and is locked:
  • These invoices need to be managed or voided directly in Xero
Fix - if there’s an invoice number clash:
  1. Go to Settings → Data Export
  2. Find the Next Invoice Number field
  3. Increase the value by five to ten (for example, if the current value is INV-100, change it to INV-105 or INV-110)
  4. Click Save and retry the export

​
Running into issues?

If your issue isn’t listed here, contact the Visualcare helpdesk.

Integration troubleshooting

General Xero, KeyPay, and data export errors

Xero integration

Set up and configure the Xero integration

Exporting payroll data

How to export timesheets and payroll data from Visualcare

MYOB export troubleshooting

Common MYOB export errors and fixes