Xero integration: troubleshooting

Fixes for common problems with the Xero integration, then a table of error messages. For how the integration works, see Xero integration; for step-by-step instructions, see Xero integration: how-to.

Tip

Sync “errors” usually mean COHO couldn’t send one item, not that anything is broken. Click Errors on the sync to see each one. Fix the cause, then sync again; the rest of the sync still went through.

I can’t see Connections & Synchronisations, or its buttons

Why it happens: the accordion needs Integrations (view) permission. Add Xero account, connecting and Disconnect need Integrations (edit). The mapping pages need Finances permission.

How to fix it: ask an admin in your organisation to give your role the permission you need. With Integrations but not Finances, the panel says “You do not have access to finances, but you can still manage the Xero integration below.”

There’s no View link on my integration

Why it happens: View only appears once the integration has been connected to Xero.

How to fix it: click the Xero connect button on the row and sign in to Xero. See Connect COHO to Xero.

The mapping lists say “No items found”

Why it happens: COHO hasn’t pulled your Xero accounts, tax rates, tracking categories and contacts yet. This is common on a newly connected integration.

How to fix it: on the Xero page, under Synchronisations, click Pull accounts, categories, and contacts. Do this again whenever you add accounts, tracking options or contacts in Xero.

“Your connection has expired”

Why it happens:

1. Nothing has synced with Xero for about 60 days, so the connection lapsed.
2. COHO was removed from your Xero organisation’s connected apps, or Xero refused COHO’s access during a sync. COHO then marks the connection as needing to reconnect.

How to fix it: click Reconnect and sign in to Xero, choosing the same Xero organisation. Your settings and mappings are kept. To stop it lapsing, turn on automatic sync. See Reconnect Xero.

Nothing is happening in Xero

Why it happens:

1. No sync has run. COHO only sends changes when a sync runs, by hand or on the automatic schedule.
2. Automatic sync is off, or the sync type isn’t switched on under Automatic Xero sync.
3. Automatic sync is paused because the last full sync of that type had errors. The badge says Auto sync blocked, and you’ll have an Action.
4. The connection has expired.
5. Rent charges are only invoiced a set number of days before they’re due, or once paid, depending on Create rent invoices days ahead.

How to fix it:

1. Check the sessions table on the Xero page: is there a recent sync, and does it have errors?
2. Clear the errors, then run a full sync of that type for the whole connection. See Read and clear sync errors.
3. Check Automatic Xero sync under Edit, including which sync types are on, and the “Last scheduler attempt”.

Automatic sync is blocked, or partially blocked

Why it happens: Pause automatic syncs when the latest connection-wide sync has errors is on (the default), and the last full sync of that type had errors or was stopped. “Partially blocked” means some sync types still run.

How to fix it:

1. Open the Action, or the latest full sync of that type, and click Errors.
2. Fix the causes, then run a full sync for the whole connection (for example Synchronise tenancies in [n] properties).
3. When it finishes with no errors, the Action closes and automatic sync resumes.

If an error can’t be fixed for now, you can set the pause to No under Edit. Automatic syncs then run despite errors.

Caution

Clicking Stop on a full sync also counts as an error and pauses automatic sync of that type until a full sync completes cleanly.

“Please add missing mapping in COHO under Chart of Accounts -> …”

Why it happens: COHO doesn’t know which Xero account to use for that item. The message names the section, the item and the ownership type, for example “Rent charges for category Deposit (Managed)”.

How to fix it: open Chart of Accounts, find that section and row, and choose an account in the column named in brackets. Then sync again.

Note

Costs your organisation pays from its own account and recovers from the owner use the Owned properties & disbursements column, even for managed properties. Only costs paid straight from client money use the Managed properties (Client Money) column.

“Account must be valid” or “Account id … is not a valid id for this document”

Why it happens: the account you mapped can’t be used for that kind of item in Xero. Usually a bank account (such as your client account) is mapped under Rent charges or Settlements & supplier expenses, or a normal account is mapped under Rent payment sources or Bank accounts. It can also mean the account has been archived in Xero.

How to fix it: in Chart of Accounts, map Rent charges and Settlements & supplier expenses to income, expense or liability accounts (for managed property, often your property control account), and payment sources and bank accounts to bank accounts. Click Pull accounts, categories, and contacts if you’ve changed accounts in Xero, then sync again.

“… because no property ownership defined on Property …”

Why it happens: rent can only be sent for properties with ownership details (owned, rent-to-rent or managed).

How to fix it: on the property, open the property ownership panel and fill in the ownership type and owner. Then sync again. On Tracking Categories, these properties are listed under Ownership Information Missing or Incomplete.

A tenancy or property isn’t being synced

Why it happens:

1. The property doesn’t use Rent Collection, or has been deactivated.
2. The property belongs to another integration (by owner or tag), or matches two integrations at once.
3. The tenancy doesn’t overlap your Staging date (Sync items from) and Until, or has been deleted.

How to fix it: check the property’s services and status, and which integration covers it (“This connection contains [n] properties” on the Xero page). If it matches two integrations, change its tag or the integrations so it matches one.

Caution

Deleting a tenancy or deactivating a property doesn’t remove what’s already in Xero. If you need those invoices gone, use Remove tenancy data from Xero first, or correct them in Xero.

“The payment is not fully associated” or “not associated to any rent charges”

Why it happens: COHO only sends a payment once all of it is matched to rent charges.

How to fix it: in the tenant’s rent schedule in Rent Collection, assign the rest of the payment to charges. Then sync the tenancy again. See Rent Schedules & Rent Collection.

“Cannot create rent payment … because the Xero invoice it needs to link to has not been created”

Why it happens: the charge the payment is matched to hasn’t got a Xero invoice yet, usually because creating it failed earlier in the same sync (for example an archived contact or a missing mapping).

How to fix it: fix the other errors for that tenancy first, then sync again. If it persists, sync the tenancy with Incremental unticked, or with Force update (very slow).

“Xero rejected this because the contact it is posting to is archived”

Why it happens: the tenancy, supplier or owner is linked to a Xero contact that’s been archived. Xero won’t add invoices to it. The archived contact may not have the same name as the tenant or supplier in the error. For example, a tenancy can be linked to an old contact that has its tenancy number as the account number.

How to fix it:

1. In Xero, search your archived contacts by account number (such as the tenancy number) as well as by name.
2. If that archived contact is the right one, unarchive it in Xero.
3. If it isn’t, link the right contact under Contacts in COHO instead. Don’t unarchive the wrong one.
4. Sync again.

Duplicate contacts in Xero

Why it happens: COHO creates a contact for anything not linked under Contacts. If the contact already existed in Xero with a different name or account number, you get two.

How to fix it: before your first sync, link existing contacts under Contacts or click Match tenancy contacts. To tidy up afterwards, merge the contacts in Xero and check the mapping in COHO points to the one you keep.

A Xero contact still shows an old tenant name

Why it happens: COHO names a contact when it creates it and doesn’t update it later.

How to fix it: edit the contact’s name in Xero. COHO keeps using the same contact.

I deleted or voided a COHO invoice or bill in Xero

Why it happens: Xero doesn’t let anyone restore a deleted or voided invoice, so COHO can’t update it.

How to fix it:

• Rent invoice: COHO notices on the next sync, drops its link and says “Please re-run synchronisation to make a new invoice”. Sync again to create a fresh one.
• Settlement or supplier bill: the error repeats on each sync. If the item is still right in COHO, contact COHO support. If it shouldn’t be in Xero, remove it in COHO (delete the settlement, or reverse the financial item) and sync again.

Make changes in COHO and let the sync update Xero, rather than editing COHO’s invoices in Xero.

“Cannot mark invoice as deleted (VOIDED) because it has payments reconciled against it”

Why it happens: you removed something in COHO, so COHO is trying to void its Xero invoice or bill, but a payment was added to it in Xero. COHO can’t remove payments it didn’t create on bills.

How to fix it: in Xero, remove or unreconcile the payment on that bill. Then run the sync again. Until you do, the error repeats and can pause automatic sync.

Rent payments appear twice in Xero

Why it happens: COHO already sends each rent payment. If your bank feed line is also turned into a new payment in Xero (by hand or by a bank rule), it’s counted twice.

How to fix it: in Xero, match the bank line to the payment COHO created instead, and check your bank rules. If a payment added in Xero overpays a COHO invoice, the next sync removes it. See Reconcile rent in Xero alongside COHO.

Managed rent invoices show No VAT

Why it happens: rent on managed properties is client money, so COHO sends it without VAT. VAT is only split out on owned and rent-to-rent properties.

How to fix it: nothing to fix; this is how the integration works. For owned property, check Tax Rates is mapped if VAT is missing.

A supplier item I marked as paid went back to Unpaid

Why it happens: for supplier bills, Xero decides the paid status. If the bill is unpaid in Xero, the next supplier sync sets the item back to Unpaid in COHO.

How to fix it: pay or mark the bill paid in Xero, then sync suppliers or click Pull back supplier payments statuses.

A settlement is paid in COHO but its bill is unpaid in Xero

Why it happens: you marked it paid in COHO before allocating the payment in Xero.

How to fix it: allocate the payment in Xero. COHO leaves the settlement as paid in the meantime; it doesn’t change it back.

A supplier’s bills aren’t syncing

Why it happens:

1. The financial item uses Misc. Supplier rather than a specific supplier, so it isn’t sent.
2. The financial item isn’t linked to a property in this integration.
3. Another item for the same supplier has a problem. COHO then stops all of that supplier’s items for the sync and lists them: “Unable to proceed with [supplier]. Out of [n] financial items [n] fail.”

How to fix it: fix the item named in the error, then sync again. The supplier on a financial item can’t be changed after it’s created; see Suppliers and Finances & reports.

“Cannot process … that is partially kept”

Why it happens: the integration doesn’t support a deposit or holding deposit that’s partly kept and partly returned.

How to fix it: split the money in the rent schedule into separate charges, or correct this one in Xero by hand. The error will repeat on each sync until it’s split.

“… its keep-related counterpart falls outside the staging window”

Why it happens: a kept deposit’s original charge and its “kept” charge fall on either side of your staging date, so COHO can’t send half of it.

How to fix it: move the Staging date (Sync items from) under Edit so both are included, or correct it in Xero by hand.

“Conflict with end of year lock”

Why it happens: the item is dated before your Xero lock date, and Xero won’t let it be changed.

How to fix it: if the amount hasn’t changed, ignore it; COHO skips it with a warning. If it has, record the correction as a new charge or financial item dated today in COHO, or move the lock date in Xero with your accountant’s agreement.

The sync is stuck on Queued or Running

Why it happens: only one sync runs at a time per integration. Big syncs take a while, and automatic syncs may be running in the background.

How to fix it: wait, or click Stop. A sync that stops responding for 5 minutes is marked Aborted automatically. Then start it again.

Error messages

Message	Why	What to do
“To enable auto syncing you must select which type of auto syncs you want to happen”	Automatic Xero sync is Yes but no sync type is turned on	Turn on Sync tenancies, Sync property owner settlements or Sync supplier items
“Making this change will result in two active Integrations overlapping. Archive or delete the conflicting integration first.”	Another integration already covers the same owner, tag or all properties	Archive the other integration, or choose a different owner or tag
“Unable to determine property list for configuration by tag ‘…’. You have conflicting configurations with [n] properties overlapping…”	Properties match both an owner integration and a tag integration	Change the tags or integrations so each property matches one
“This integration previously had a different XERO account linked and this account (XERO Tenant) is no longer authorised.”	You reconnected to a different Xero organisation	Reconnect and choose the original organisation, or add a new integration
“This integration authorisation has returned no accounts as accessible.”	No Xero organisation was allowed during sign-in	Connect again and allow access to an organisation
“The returned result from XERO had no code value. You may have cancelled the process, try again.”	Xero sign-in was cancelled	Connect again
“The Xero refresh token is no longer valid. Please reconnect your Xero account.” / “Please reconnect your Xero account.”	The connection has expired or was removed in Xero	Reconnect
“Cannot start a new XERO synchronisation session while an existing one named ‘…’ is queued/active since ‘…’”	Another sync is running	Wait, or Stop it
“Please add missing mapping in COHO under Chart of Accounts -> …”	A mapping is missing	Map it in Chart of Accounts
“Input fed to Xero failed their validation check: …”	Xero rejected the item; the part in quotes says why, for example “Account must be valid.”	Usually fix the mapping; see the entries above
“Cannot synchronise rent dues for Tenancy[…] because no property ownership defined on Property[…]”	Property has no ownership details	Add ownership details
“Unable to proceed with … because it is not contained within the valid properties for this configuration.”	The tenancy or item belongs to a property outside this integration	Sync it from the right integration
“Skipping linking XERO Contacts to … as multiple XERO Contacts exist that match the tenancy number ‘…’.”	Several Xero contacts contain the tenancy number	Link the right one under Contacts, or tidy up the contacts in Xero
“Cannot create contact because one already exists with the same name. Recommend you map the contact manually in the COHO Contacts section.”	A Xero contact already has that name	Link it under Contacts
“Xero rejected this because the contact it is posting to is archived. That contact may not be named after the tenant or supplier in this error, so search archived contacts by account number as well as name. Unarchive it only if it is the right contact; otherwise remap the record in COHO Contacts Mapping.”	The linked contact is archived	Find it in Xero by account number or name. Unarchive it if it’s the right contact; otherwise link the right one under Contacts. See the entry above
“Skipping … The payment is not associated to any rent charges.” / “The payment is not fully associated. £… remains to be associated to rent charges.”	The payment isn’t fully matched to charges	Assign it in Rent Collection
“More money is associated from the payment than the payment amount. Raise a support ticket for assistance.”	The payment’s matches add up to more than the payment	Contact COHO support
“Cannot create … because the Xero invoice it needs to link to has not been created (or is not loaded).”	The charge’s invoice failed or is missing	Clear other errors, then sync with Incremental unticked or Force update
“Failed (API does not support restoring deleted invoices)” / “… because XERO API does not support restoring deleted invoices (restore it in XERO)”	The invoice or bill was deleted or voided in Xero	See I deleted or voided a COHO invoice or bill in Xero
“The invoice to be updated has been deleted in XERO.”	As above, for a rent invoice	Sync again to create a new one
“Cannot mark invoice as deleted (VOIDED) because it has payments reconciled against it…”	A payment was added in Xero	Remove or unreconcile it in Xero, then sync
“The API would not complete the request as that would result more money being reconciled against an invoice than the total amount due on the invoice…”	A payment added in Xero is in the way	COHO tries to remove it; if it can’t, remove it in Xero
“The invoice cannot have a payment applied to it as its status is not set as AUTHORISED (did you delete it? Or set it to DRAFT?)…”	The invoice was changed in Xero	Set it back to approved in Xero
“Cannot edit document (invoice/bill) as it has a payment or credit note allocated against it.”	A payment or credit note in Xero blocks the change	Remove the allocation in Xero, sync, then re-allocate
“Cannot edit settlement party Bill-To-Pay/Invoice on XERO when it has status PAID - Will not update …”	The settlement’s bill is already paid in Xero	Remove the payment in Xero, sync, then reconcile again
“Conflict with end of year lock …”	The item is before your Xero lock date	See Conflict with end of year lock
“Cannot process … that is partially kept (not supported with the Xero integration). Fix the rent book by manually splitting out the money.”	Partly kept deposit	Split the charges, or fix it in Xero
“Cannot synchronise … because its keep-related counterpart falls outside the staging window…”	Staging date splits a kept deposit	Move the staging date
“The total for this document (invoice/bill) cannot be 0 or negative…”	A negative or zero charge or item	Check the amount in COHO
“File type being uploaded is not supported by the XERO platform” / “File on COHO is empty (0 bytes) and cannot be pushed to Xero.”	The attached invoice or statement file can’t go to Xero	Replace the file with a PDF or image
“Email address for contact creation is not valid (According to XERO System).”	The tenant’s, supplier’s or owner’s email isn’t valid	Correct the email in COHO
“Could not find any organisation person (team member) to use as the contact person for the XERO contact”	COHO needs a team member to create your organisation’s contact	Link This organisation under Contacts
“You have a tracking option with this name already”	Add option with an existing name	Use the existing option
“This connection cannot create new tracking options. Please reconnect your Xero connection to proceed.”	The connection doesn’t allow creating options	Reconnect, then try again
“The tracking option was added to Xero but it could not be retrieved and added into COHO. You need to pull the categories in order to bring the tracking category option into COHO.”	Created in Xero, but not brought back	Click Pull accounts, categories, and contacts