When an invoice syncs or cancels in Xero, something can fail even though the invoice looks fine here. You’ll usually see it in an email alert, a toast, the invoice Xero banner, booking Activity, or Settings → Integrations → Xero → Recovery.
Find the wording below that matches what you saw. Each entry explains what went wrong and how to fix it. For connection setup, account mappings, and tax settings, see Connect Xero.
After you fix the underlying issue, open the invoice (or the voided invoice) and use Sync with Xero or Retry from the invoice actions or Recovery. Confirm booking Activity shows a successful sync. A voided invoice stays voided here even when Xero cancel fails — retry only updates the Xero side.
Account code or ID must be specified
What you might see: An email or alert that a void push failed, sometimes ending with “Account code or ID must be specified”. Newer alerts may say the cancel credit note needs a chart account.
What went wrong: The bill was sent to Xero with Send without account, then authorised or paid in Xero. Cancelling it needs an authorised credit note, and Xero requires a chart account on those lines. When the Xero bill lines already have a chart account (for example someone set one in Xero after sync), cancel usually reuses that account automatically — you mainly see this error when those lines still have no account, or the cancel could not match them.
How to fix:
The invoice is already voided here — you do not need to void it again.
Retry sync on the voided invoice first — if the Xero bill already has chart accounts on its lines, cancel often completes without changing Settings.
If retry still fails, open Settings → Integrations → Xero → Accounts and map Booking invoices (and other types you authorise or pay) to a real chart account instead of Send without account, then retry again.
If invoices forward to a roster member’s Xero, check that member Account’s chart mapping too — not only the owner Account.
If retry still fails — especially when the bill is already paid and reconciled in Xero — see Bill already paid in Xero below.
Bill already paid in Xero
What you might see: A void alert or email mentioning the bill is already been paid off, or that a credit note cannot be allocated because the amount is greater than amount outstanding.
What went wrong: The bill was fully paid in Xero before you voided it here. Cancelling an authorised bill uses a credit note allocated against what is still owing. When the balance is $0, Xero rejects the allocation — even though the credit note itself may have been created.
How to fix:
The invoice is already voided here — you do not need to void it again.
In Xero, finish the cancel with your usual paid-bill process: remove or reverse the payment, add a refund or credit note, or void the bill there — especially if the payment is already bank-reconciled (your accountant may need to do this).
If a stray credit note was created in Xero during the failed sync, void or delete it in Xero so the ledger stays tidy.
Retry sync here only if your team still expects Muzeek to update Xero after you fix the bill in Xero.
Tip for testing or new voids: If the bill is only Awaiting payment in Xero (authorised but not paid), void sync from here usually completes without this error.
Invoice number already used in Xero
What you might see: A sync failure saying an invoice with the same number already exists in Xero (and to change your invoice prefix under Settings → Invoices). Older alerts may still quote Xero wording about LineItemID, that the date cannot be changed because payments or credit notes are allocated, that DRAFT cannot be applied to a paid invoice, or Invoice not of valid status for modification.
What went wrong: Sync tried to create a new Xero bill or invoice using the same number as one that already exists there — often INV-001 or INV-002. Xero treats that as an update of the existing document. If that document is already paid, voided, or otherwise locked, Xero blocks the change. The wording varies with the existing document’s status. This can happen even when the invoice here has never synced, because someone already entered a bill with that number in Xero (or Xero already used that number). It can also happen after you disconnect and reconnect Xero: the invoice may already be in that Xero file from the earlier connection. If this invoice already has a Xero link and you were only changing details, this is not a number collision — retry after unlocking or finishing the change in Xero, and do not void just to change the prefix.
How to fix:
In Xero, search bills (or invoices) for that number and the same contact.
If it is already this same booking amount (including a draft you synced earlier), you do not need a new number — retry Sync with Xero. If you recently reconnected Xero, retry first; do not change the prefix or void the invoice just to get a new number.
If it is a different, older document with the same number, give this invoice a unique number. Open Settings → Invoices, change the invoice number prefix to something your Xero file does not already use (for example KST- instead of INV-), then void this invoice and create it again so the new number is used. Retry Sync with Xero.
Ask your accountant before changing a paid document’s number in Xero.
Tip: If you already use INV- in Xero, set a different prefix here before the first sync so later invoices do not collide.
This Xero contact is already linked to another contact
What you might see: An email titled Xero invoice sync failed, a toast, or a Recovery row, with wording like:
Could not connect [contact] because [contact] in Xero is already connected to [other contact].
Could not connect [contact] because that Xero contact is already connected to another contact with the same name.
Older emails: Could not create a separate Xero contact for [contact] because Xero matched an existing contact already linked to another Muzeek contact.
What went wrong: Xero only allows one contact with a given name. That Xero contact is already connected to a different contact record here. The invoice is not sent to the wrong Xero contact.
Common causes:
The same venue or company exists twice in Contacts (same name, two records).
Someone already connected that Xero contact from Contacts → Sync to Xero on a different record.
How to fix:
Retry the invoice from Recovery or the invoice actions. If the Xero contact is free, it is reused. A second Xero contact with the same name is not created.
If it keeps failing, open Contacts and look for a duplicate with the same name. Newer emails name the other contact when the names are different.
Keep the contact that is already on the booking, then retry from Recovery.
Xero will not keep two contacts with the same name.
The invoice is already in Xero, but the PDF didn’t attach
What you might see: Newer alerts say this invoice is already in Xero, a PDF couldn’t be attached this time, and you don’t need to void it or change the invoice prefix. Older emails may quote Xero wording about an Idempotency Key and used with a different request, sometimes with a long muzeek:invoice:…:pdf string.
What went wrong: The invoice was already sent to Xero. A later sync tried to attach an updated PDF, and Xero blocked that second attach. The document in Xero is still there — nothing was lost.
How to fix:
Open the invoice in Xero — it’s already there. You don’t need to recreate it.
Retry Sync with Xero from the invoice actions or Recovery if you want the latest PDF attached.
If a retry still doesn’t attach it, add the PDF in Xero yourself.
You don’t need to change your invoice prefix or void this invoice.
Xero didn't finish this invoice
What you might see: “Xero didn't finish this invoice. Your connection is fine — open it and use Sync with Xero to try again.” Older emails may still say reconnect even when Connection looks fine.
What went wrong: Xero timed out or sent back an empty error. That can happen after the bill is already created. Your connection is fine — a timeout is not the same as access being revoked.
How to fix:
In Xero, search bills (or invoices) for that number. A timeout can create the document, then fail to reply.
If it's already this invoice, you don't need to recreate it or change the prefix.
If it's missing, open the invoice and use Sync with Xero, or retry from Recovery.
Only reconnect if Settings → Integrations → Xero → Connection shows an error, or the alert says access was revoked or expired.
Xero didn't finish on their end
What you might see: “Xero didn't finish on their end. Your connection is fine — try again.”
What went wrong: Xero timed out or sent back an empty error on a request that is not this invoice. Your connection is fine — try the same action again. A timeout is not the same as access being revoked.
How to fix:
Try the same action again.
Only reconnect if Settings → Integrations → Xero → Connection shows an error, or the alert says access was revoked or expired.
Xero access was revoked or expired
What you might see: “Xero access was revoked or expired. Reconnect under Settings → Integrations → Xero → Connection, then try Sync with Xero or Recovery.” Connection shows an error.
What went wrong: Xero rejected the saved access — usually invalid grant, a 401, or AuthenticationUnsuccessful. That is a dead connection, not a timeout.
How to fix:
Open Settings → Integrations → Xero → Connection.
Select Reconnect and approve access again.
Retry the invoice from Recovery or the invoice actions.