Troubleshoot and fix QuickBooks sync errors
Learn why your data isn't syncing to QuickBooks and follow clear steps to identify and resolve common errors. Keep your financial records accurate and up-to-date.
This guide shows you how to find and fix common errors with the QuickBooks Online integration. Resolving sync issues quickly ensures your bookkeeping is accurate and your financial reports are reliable.
When you connect AtomicSam to QuickBooks Online, data like clients, invoices, and payments sync automatically. Sometimes, a configuration issue or a change in one of the systems can cause this sync to fail for a specific record. You can find, diagnose, and fix these issues using the sync error log.
Before you start
- You need administrator permissions in your AtomicSam organization.
- You need administrator access to your QuickBooks Online account.
- You must have an active connection to QuickBooks Online.
Find the sync error log
The sync error log is your starting point for any troubleshooting. It lists every record that has failed to sync and provides the reason why.
- Navigate to Settings → Integrations.
- Locate the QuickBooks Online card and click Manage.
- Select the Sync Errors tab.
- You will see a list of all items that have failed to sync. Each entry includes the date, the type of record, and an error message from QuickBooks.
Resolve common errors
Most sync errors fall into a few common categories. Use this table to identify the error you are seeing and learn how to resolve it.
| Error Category | What it means | How to fix it |
|---|---|---|
| Missing or Unmapped Data | An item from AtomicSam, like a tax rate or line item, does not have a corresponding item mapped in QuickBooks. The error message often includes “not found”. | Go to the integration settings and map the AtomicSam item to the correct QuickBooks item in your Chart of Accounts. If the item does not exist in QuickBooks, create it there first, then refresh the integration settings to map it. |
| Authentication Failure | AtomicSam is no longer authorized to access your QuickBooks account. This can happen if the connection is revoked from within QuickBooks. The error might say “Authentication Failed” or “Access Token Expired”. | On the Manage page for the QuickBooks integration, click Reconnect. You will be prompted to log in to QuickBooks and re-authorize the connection. This does not affect your existing data. |
| Invalid Reference ID | A record synced from AtomicSam (like a Client) was deleted or merged in QuickBooks. The link between the two systems is now broken. |
This error requires careful handling. You may need to restore the deleted record in QuickBooks. If that is not possible, you may have to archive the record in AtomicSam and create a new one to establish a new sync link. ⚠️ Heads up: Modifying data to fix this type of error can have unintended consequences. Contact our support team if you are unsure how to proceed. |
| Duplicate Record | You are trying to sync a record with a name or number that already exists in QuickBooks, such as an invoice with a duplicate number. | Find the record in QuickBooks. If it is an unintended duplicate, you may need to rename or delete the record in QuickBooks. Or, you can change the invoice number or client name in AtomicSam and retry the sync. |
| Closed Accounting Period | You are trying to sync a transaction to a financial period that has already been closed in QuickBooks by you or your accountant. | Consult your accountant. They may need to temporarily reopen the books to allow the transaction to sync. Alternatively, you can edit the date on the transaction in AtomicSam if it was entered incorrectly. |
Retry a failed sync
After you fix the underlying issue, you must tell AtomicSam to try syncing the record again.
- Return to the Sync Errors tab under Settings → Integrations → QuickBooks Online.
- Find the error you resolved in the list.
- Click the Retry button for that specific line item.
- If your fix was successful, the item will disappear from the error log. If it fails again, the error message may update with new information.
💡 Tip: If you solved a problem that affects many records (like a missing tax mapping), you can use the Retry All button to re-process all failed syncs at once.
Good to know
- The sync between AtomicSam and QuickBooks runs automatically about every hour. You can also trigger a manual sync anytime by clicking Sync Now on the integration's Manage page.
- For the most reliable sync, it is best practice to create and manage records like clients and jobs in AtomicSam and let the integration create them in QuickBooks. This avoids creating duplicates.
- Some errors from QuickBooks can be vague. If you are unable to diagnose an issue from the error message, checking your mapping settings is always a good first step.