Problems
The Contact Name already exists error in Xero
It means a contact in that Xero organisation already carries the name the export is trying to write. Xero holds one contact per name, and the export creates or renames contacts by name, so a second client spelled the same way is refused. The contact holding the name can be an archived one, which is why a contact search often turns up nothing.
Key facts
- The message
- The Contact Name already exists. Please enter a different Contact Name.2
- The field it is about
- The contact name, the one Xero prints at the top of the contact record. Not the client's email, not their file number.2
- Why it fires
- A profile in Xero already shares that name combination, so the export cannot create a second contact under it2
- The durable key
- The vendor fix is to copy the Xero Contact ID off the contact's own URL and paste it into the client profile, so the next batch matches on that id rather than on the name2
- Archiving is a status
- Xero's contact status list carries ACTIVE and ARCHIVED on the same contact record, so archiving a contact changes its status rather than releasing the name and the codes it holds3
- Contact Code
- Xero describes ContactNumber as the field for identifying contacts in external systems, settable through the API only, shown as Contact Code on the contact screen, and capped at 50 characters3
- Account number
- AccountNumber is a user defined account number, editable both through the API and inside Xero, and also capped at 50 characters3
- Name length
- The contact name field holds the full name of a person or an organisation, up to 255 characters3
- After a merge
- A merged contact reports the id of the contact it was merged into, so a link stored against the old contact can be repointed rather than rebuilt3
- The rename case
- Taking the company name off a client profile makes the export try to rename the Xero contact, and that rename fails where another contact already carries the new name2
- Not one vendor
- Cliniko documents the same rename failure when a patient name is corrected after the first sync, so the behaviour sits in Xero rather than in one export4
What the error says, and when you see it
The message arrives mid batch, not at set up. A practice system exports a run of invoices to Xero, most of them land, and one stops with a line that reads: The Contact Name already exists. Please enter a different Contact Name. Nothing on the invoice is wrong. The export did not get as far as the invoice, because it could not write the contact the invoice would hang off.
A client becomes a Xero contact the first time an invoice for them is exported. Every batch after that either finds the contact again or writes a new one. This error is the second half of that sentence failing: the export went to create a contact, and the name it wanted was taken.
Read the field, not the message
Four different errors in the same troubleshooting list all say some version of this value is taken, and they sit on three different fields plus a rename. That is why the fix so often lands on the wrong one. Xero publishes what each field is for, which is enough to tell them apart before anyone opens a contact record.
Which of the four you have
The message text is the whole diagnosis. Match it against the table below, then go looking for the thing that is holding the value rather than for a duplicate in general.
| The message | The field | What is holding it |
|---|---|---|
| The Contact Name already exists | Contact name | Another contact, active or archived, spelled the same way |
| Another contact has this contact number | Contact number, shown as Contact Code | A contact already carrying the client number this export writes. The field is settable through the API only, so an app put it there rather than a person |
| The account number already exists | Account number | A contact carrying the same account number, which a person can also have typed in by hand |
| The existing contact with name X cannot be updated to use new name Y | Contact name, on a rename rather than a create | A contact already carrying the new name, so the rename has nowhere to land |
The company name trap
The fourth error has a mechanism worth knowing, because it fires on a client whose contact was created cleanly months ago. Where the client profile carries a company name, the export uses that as the Xero contact name. Take the company name off later, and the next export tries to rename the contact to the person's name. If a contact under that person's name already exists, the rename fails and the batch stops.
The existing contact with name 'ABC Pty. Ltd.' cannot be updated to use new name 'Damien Test'. There is an existing contact with that name.2
Cliniko documents the same failure from a different starting point: a patient name corrected after the first sync, a spelling fixed, and the same rename refused. Two vendors raising one message is the tell that the constraint sits in Xero, so changing export vendors does not change it.
Why the name looks free when it is not
The most common wasted half hour on this error is searching the Xero contact list, finding nothing, and concluding the message is wrong. Archiving a contact does not release what it holds. The name, the contact code and the account number stay attached to it, and a normal contact list does not show it.
Zanda's troubleshooting page sends the reader to archived contacts first for the two code errors, and Cliniko carries a separate error for the case where the contact the invoice needs is archived rather than missing. So an archived contact is worth ruling out before anything is renamed.
Clearing it, in the order that holds
- Read the message and name the field: contact name, contact number, account number, or a rename.
- Search Xero for the value that field is carrying, with archived contacts included, not for the client.
- Decide which contact survives. The one the export created is the one the export can find again, because it carries the contact code the practice system wrote.
- Un-archive anything you need to act on, then merge so one contact holds the name and the codes.
- Where the export offers a manual link, paste the surviving contact's Xero Contact ID into the client profile, which is what stops the next batch matching on the name.
- Re-run the export for that client and check the invoice landed before running the payments batch, since payments export separately and need the invoice to be there.
Step three is the one people get backwards, and duplicate patient contacts in Xero is the page that works through the choice and what it costs to get it wrong.
What it costs while it sits there
One refused contact is not one missing invoice. The export runs invoices first and payments second, so an invoice that did not land takes its payment with it. The client's revenue is missing from the period, the payment has nothing to attach to, and where that money arrives as part of a funder deposit, the clearing account for the rail is left holding the difference.
It also compounds quietly. A practice that answers the error by exporting the client under a slightly different name now has two contacts for one person, and the next name change picks a fight with whichever one it lands on. That is how a single refused write becomes the duplicate contact problem a year later.
Keeping it from coming back
The constraint is not going away, so the work is to stop the export depending on the name. Three habits do most of it.
- Link by id, not by name. Where the practice system has a field for the Xero contact id, filling it in for the clients that have clashed removes the name from the matching path.
- Leave the contact code alone. It is the export's own marker, and it is what tells you which of two contacts the practice system will look for next time.
- Change names in one place. A correction made in the practice system travels to Xero as a rename; a correction made in Xero does not travel back, and the two then disagree.
None of that is a Xero setting. It is a habit about which system owns a client's name, which is why the error keeps arriving at practices that have already fixed it once.
What Ledger Map does with it
Ledger Map holds one standing map for the practice, approved before anything syncs, and keys a client to the contact id rather than to the spelling of a name. A write it cannot place becomes a question with the options laid out, rather than a second contact created quietly under a name that was free.
On the money side the same rule holds: one balanced document set per deposit, against the accounts the map names, leaving one exact match in the bank feed for the bookkeeper to click. You can see how the map is approved on how it works, or read the rest of the sync failures on the learn hub.
Questions
Why does Xero say the contact name already exists?
Because a contact in that organisation already carries the name the export is writing. The export creates a contact from the client's name, or from the company name where the client profile has one, and Xero holds one contact per name. The contact holding it is often archived, so it does not appear in a normal contact search.
Can two contacts have the same name in Xero?
Not in the same organisation, which is what the error is telling you. The vendor troubleshooting pages treat a shared name combination as the cause and send you to link the client to the existing contact instead. Whether Xero will keep enforcing that is an open question on this page rather than a settled fact.
What is the difference between another contact has this contact number and the account number already exists?
Different fields. Contact number is the external system slot Xero shows as Contact Code, which can be written through the API only, so a clash there usually means an earlier connection already claimed that client number. Account number is user editable in Xero as well, so a clash there can be something a person typed in by hand.
Why did the export try to rename my Xero contact?
Because the name it wants changed. Where the client profile carried a company name, the Xero contact was created under that name; taking the company name off makes the next export rename the contact to the person's name. If a contact already holds that name, the rename is refused and the batch stops on it.
Does merging the contacts fix it permanently?
It clears the batch. It stops the error coming back only if the export can find the surviving contact without the name, which means filling in the Xero contact id in the client profile where the practice system offers that field, and leaving the contact code the export wrote in place.
Read next
- ProblemsDuplicate patient contacts in Xero
- ProblemsAn invoice failed to sync with Xero
- ProblemsInvoice not of valid status for modification
- ProblemsDeleted Zanda invoice is still in Xero
- ProblemsDocument date cannot be before the lock date
- Practice systemsCliniko Xero integration: what syncs, what does not
- HubProblems
Sources
Open questions
- How long Xero holds one contact per name, and the wording of its own warning that the field may not stay unique. The Contacts API reference renders through JavaScript and returned no body text on 3 Sep 2026, so that warning is noted here rather than quoted, and the constraint is stated as the vendor pages state it.
- The exact behaviour of a create call that carries a name and no contact id, which may match and update the existing contact of that name rather than failing. The corpus records it as unverified, so nothing on this page depends on it.
- The Cliniko article gives no dated last update, only that it was updated over three weeks before it was read, so its retrieved date is the only firm date on it.
- Two of the results describing this error for other products, at BILL and at splose, could not be opened on 3 Sep 2026, one returning 401 and the other having moved. What they say is recorded from the search snapshot and is not cited as a fact here.
- Xero Accounting API specification, version 18.0.0, the Contact schema
Xero. Retrieved 3 Sep 2026.
primary
Review
Last reviewed 3 Sep 2026 by Shane
General information for Australian allied health practices, not tax advice. Confirm a treatment with your BAS agent or accountant before you post it.
Guided onboarding
Run one real month before you go live.
Sign up, connect Zanda and Xero, and replay a month you already closed. The map is reviewed with whoever owns the books, and nothing posts until you approve it.
Every practice starts from a template. Nothing posts until the map is approved.