Why a Sync Failed and How to Retry It

If something doesn't sync as expected, two screens tell you what happened: Sync History on the Configuration home screen for the run, and the Debug Log Viewer for the record and the exact error.

Read Sync History

Configuration → Home → Sync History lists recent runs. A run marked Sync Issues rather than Sync Completed had at least one failure, and its Records Failed link opens the list. The run itself continues past a failed record; failures don't stop the schedule. See Reading the sync history.

Read the debug log

Configuration → Tools → Debug Log Viewer groups every error and warning by issue type, with a count, when it was first and last seen, and the record involved. The error text is Xero's own message translated into plain language, and it usually names the field or setting at fault. See Downloading and reading debug logs.

Common causes

• Field mapping — a required Xero field is empty, or a mapping points at a field that no longer exists. See Mapping fields.
• Permissions — the user the sync runs as can't see a record or field involved. The log says Please check access to these fields and lists them.
• Account not matched — the Salesforce Account isn't linked to a Xero contact, or the contact is archived in Xero. See Account matching.
• Your own automation — a validation rule or required field on Account or Opportunity rejected the sync's write. See When your own automation blocks the sync.
• Lock date — the document is dated before Xero's lock date. The record is flagged Blocked By Lock Date with the reason.
• Xero's API limit — the run paused because the daily or per-minute allowance was reached. It resumes on its own. If it happens often, the API Floor Settings under Advanced Settings reserve headroom; change them with support.

Retry

Once you've fixed the cause, push that record again from its own page: Send To Xero on the record, or Resync With Xero on an invoice to reconcile the two copies. There's no need to recreate anything. See Send To Xero and Resync.

For many records at once, the scheduled sync retries failed records on its next cycles. Re-Sync Invoices and Re-Sync Payments under Advanced Settings re-pull everything for a fresh comparison.