View and fix Xero sync errors
Learn how to find the Xero sync error log and resolve common issues. This keeps your financial data accurate across both AtomicSam and Xero.
This guide shows you how to find and resolve common Xero sync errors. Keeping your sync healthy ensures your financial data is accurate in both AtomicSam and Xero.
When you connect AtomicSam to Xero, data like your clients and invoices syncs automatically. Sometimes this sync can fail if there is a mismatch between the two systems. You can find a log of these failures inside your integration settings.
Before you start
- You need Administrator permissions to view and manage integrations.
View your sync error log
The first step is to locate the errors. AtomicSam logs every sync failure with a reason to help you diagnose the problem.
- Open Settings → Integrations.
- Find the Xero integration in the list and click Manage.
- Select the Sync Errors tab to see a list of all failed items. Each error includes the date, the type of record, and a message from Xero.
💡 Tip: After you fix an error, you can return to this screen and click Retry Sync on the specific item to push the changes through immediately.
Resolve common errors
Most errors happen because information in AtomicSam does not match the information in Xero. The table below explains the most common errors and how you can fix them.
| Error Message | What it means | How to fix it |
|---|---|---|
| The contact with the specified contact name already exists | A Client in AtomicSam has the same name as a contact in Xero, but they are not linked. This can happen if the contact was created manually in both systems. | In Xero, merge the duplicate contact with the correct one. If there is no duplicate, archive the conflicting contact in Xero and retry the sync from AtomicSam. |
| Invoice not found | An invoice that was previously synced from AtomicSam has been deleted or voided in Xero. AtomicSam tried to update it, but could not find the original. | Open the invoice in AtomicSam and void it to match its status in Xero. If you still need the invoice, you must recreate it so it can sync as a new record. |
| Invoice #XXXX is already in use | The invoice number from AtomicSam has already been used by another invoice in Xero. Xero requires all invoice numbers to be unique. | Edit the invoice in AtomicSam and give it a unique invoice number. You can add a suffix like -A to the existing number. Then, retry the sync. |
| Account code 'XXX' is not a valid account code | The revenue or expense account code assigned to an item in AtomicSam is missing, archived, or invalid in your Xero Chart of Accounts. | Check your Chart of Accounts in Xero and make sure the account code exists and is active. Then, update the item in AtomicSam with the correct account code. |
| Authentication error | The connection between AtomicSam and Xero has been lost. This often happens if the integration is disconnected from the Xero side. | Go to Settings → Integrations, click Manage on the Xero integration, and follow the prompts to Reconnect your account. |
⚠️ Heads up: Changing data in one system to fix a sync error can have downstream effects. For example, changing an invoice number in AtomicSam after you sent it to a client may cause confusion. Always review your changes carefully.
Good to know
- Sync errors are reported for individual items, like a single Client or invoice. One error will not stop other, valid items from syncing.
- Some fixes require action in AtomicSam, while others must be done in Xero. The error message usually indicates which system needs the change.
- If you regularly see account code or tax rate errors, review your Xero integration settings in AtomicSam. You can set default accounts and map tax rates to prevent future issues.