> ## Documentation Index
> Fetch the complete documentation index at: https://support.visualcare.com.au/llms.txt
> Use this file to discover all available pages before exploring further.

# Xero export troubleshooting

> Common Xero export errors and how to resolve them in Visualcare

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.

<Tip>For general Xero connection and accounting code errors, see [Integration troubleshooting](/troubleshooting/integration-issues).</Tip>

## 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

<Note>This error is also covered in [Integration troubleshooting](/troubleshooting/integration-issues) with additional detail on pay item types.</Note>

***

### 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](mailto: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

<Note>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.</Note>

***

## 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.

## Related articles

<CardGroup cols={2}>
  <Card title="Integration troubleshooting" icon="plug-circle-xmark" href="/troubleshooting/integration-issues">
    General Xero, KeyPay, and data export errors
  </Card>

  <Card title="Xero integration" icon="building-columns" href="/integrations/xero">
    Set up and configure the Xero integration
  </Card>

  <Card title="Exporting payroll data" icon="file-export" href="/finance/exporting-payroll-data">
    How to export timesheets and payroll data from Visualcare
  </Card>

  <Card title="MYOB export troubleshooting" icon="wrench" href="/troubleshooting/myob-export-errors">
    Common MYOB export errors and fixes
  </Card>
</CardGroup>