CardDAV Write Back Troubleshooting

CardDAV write-back — when it goes wrong

Everything about diagnosing a write-back: what each result means, how to read the log, and what the two diagnostic tools are actually telling you.

This page is for the person running it. How the write mechanics work inside is on CardDAV write-back internals; the feature itself is on CardDAV contact sync.

---

The guarantee, first

A write-back can never lose an edit an analyst made.

The person's record in FreeITSM is saved first and completely. Sending the change onward to the address book happens afterwards and cannot undo it.

So every failure on this page has the same shape: the change is safe in FreeITSM, and something stopped it reaching the card. There is no failure mode where pressing Save loses your work because somebody else's server was having a bad day.

This is deliberate, and it is the reason the wording of every message starts with "Saved here, but…". The first thing you need to know is that your work survived; what happened to the address book is the second sentence.

The one asymmetry worth understanding

	Damages	Recoverable?
A bad import	FreeITSM's copy	Yes — import again
A bad write-back	your address book	No. Not by us.

That asymmetry is why write-back is cautious to the point of being fussy: it only touches five fields, only on contacts it imported, only when a human deliberately edited one, and it refuses outright rather than guessing. There is no bulk "put it all right" pass and there should never be one.

---

The four results

Every save that could have reached the address book produces exactly one of these. They appear as a message on screen and as a row on the History tab under Changes sent back.

✅ Written

The contact card was updated. The message names which details changed.

⚠️ Refused

Somebody had already changed the same detail in the address book, and FreeITSM did not overwrite them.

🔑 This is not a fault. It is the safety net doing exactly the job it exists for. If you find yourself trying to make refusals stop happening, step back — the refusal is protecting a value somebody else entered deliberately.

The message tells you their value. The log row goes further and records all three: what the card says now, what FreeITSM last imported, and what your analyst typed. That is usually enough to see at a glance who is right.

What to do: run an import. That brings their version in. Then look at the person again and decide — if FreeITSM's value was the correct one after all, edit it again and it will now go through, because there is no longer a disagreement.

⚠️ A refusal is per field. If an analyst changed the mobile and somebody else changed the job title, nothing is refused — the mobile goes through and the job title is left alone. It only refuses when both sides touched the same detail.

❌ Failed

FreeITSM could not reach the server, or the server said no. The message carries the reason, and the log row carries the server's own words.

Common causes, in rough order of likelihood:

What you see	Almost always means
Could not connect	The server is down, the address has changed, or a firewall is in the way
401 / authentication failed	See the Digest trap below before you touch the password
403 / forbidden	The account is real but that address book is read-only for it
404 / not found	The contact's card has been deleted or moved on the server
412	A rare timing case — somebody saved that card in the instant between FreeITSM reading it and writing it. Just try again

⏭️ Nothing to send

The card already matched. Common and harmless — it usually means an analyst pressed Save without actually changing any of the five details, or re-typed the same value.

It is logged as Nothing to send rather than Written on purpose: a log full of successes that wrote nothing would make a broken write-back look busy.

---

🔴 The Digest trap — read this before re-typing any password

A stock Baikal server — the most common sabre/dav install, and what most people asking for CardDAV are running — ships with Digest authentication.

Basic authentication against it returns a flat 401, which looks exactly like a wrong password. The natural response is to go and check the password, find it is correct, check it again, and conclude FreeITSM is broken.

Measured against Baikal 0.12.1:

FreeITSM's auth setting	Result
Basic	401
Digest	207 (works)
Automatic	207 (works)

So: leave the authentication setting on Automatic unless you have a specific reason not to. If you have pinned it to Basic and are getting 401s, that is your answer.

Both the connection test and D015 report which scheme the server actually offered, so you never have to guess. That single line is usually the whole diagnosis.

---

Reading the write log

System → Authentication → your address book → Configure → History tab → Changes sent back

Every attempt, newest first, whether it worked or not.

Column	What it tells you
When	In your own timezone
Person	Kept even if the person is later deleted, so the row still makes sense
Result	One of the four above
Changed	Which details were actually written
Detail	FreeITSM's conclusion in plain English, plus an expandable "What the server said"

Why the raw server response is kept

Expanding What the server said (HTTP nnn) shows the server's reply word for word, not a tidied-up version.

That is deliberate and it is the most useful thing on the page. When an address book refuses something, the actual reason is in its own error body — and FreeITSM's paraphrase of it is no use whatsoever for diagnosing a server that FreeITSM cannot log into and you may not administer either. If you are sending a problem to whoever runs the CardDAV server, that block is the thing to send them.

Reading the tally

The log is also the honest answer to "is this working?". A healthy one is mostly Written with the occasional Refused. Patterns worth noticing:

• All Refused → your import is stale. Something else is maintaining those contacts and FreeITSM has not read them recently. Import more often.
• All Failed with the same message → a configuration problem, not a data one. Go to D015.
• Nothing at all, ever → nothing has been attempted. Either write-back is off, nobody has edited one of the five fields, or the contacts are missing their card reference (D015 counts these).

---

D015 — CardDAV health

System → Debug Tools → D015

Answers "does this connection work, right now?" It contacts the server, and it writes nothing.

It walks the path a real write-back takes, one rung at a time, because they fail for completely different reasons. Being told only "it does not work" leaves you four separate things to check; this tells you which one.

Rung 1 — reach the server and sign in

Reports the HTTP status and, crucially, which authentication scheme the server offered. See the Digest trap above.

If this fails, nothing below it can be tested and the report says so. It is a network, address, or credentials problem.

Rung 2 — read the chosen address book

Signing in successfully does not mean this account can read that particular book. This rung separates the two, and reports how many contacts, groups and tags are actually in it.

If this fails but rung 1 passed, the account is fine and the book is the problem — wrong book chosen, or no permission on it.

Rung 3 — may this account write?

Asks the server what the account is allowed to do, and lists the privileges it grants.

🔴 It writes nothing to find this out. Proving write access by creating a contact and deleting it again is worse than it sounds — the delete can fail, and you are left with a contact called "FreeITSM test" in a real address book that somebody then has to explain.

⚠️ "Unknown" is not "no". Some servers simply do not report their privilege set. D015 says so rather than pretending it got an answer.

🔴 The mismatch D015 exists to catch

Write-back switched ON, and the account cannot write.

This is the nastiest configuration, because everything looks fine. Analysts edit contacts, FreeITSM saves them perfectly, and every single change is refused by the server. Without D015 you would find out from the write log, one puzzled analyst at a time.

D015 calls it out in as many words. The fix is on the address book server — grant the account write access. Nothing in FreeITSM can work around a permission the server has not given.

It also names the harmless opposite: the account could write but write-back is off. That is a perfectly good setting and it says so rather than nagging.

Rung 4 — FreeITSM's own side

Three numbers the server cannot tell you:

• People managed by this book — how many contacts became people here
• Missing a card URL — 🔴 these cannot be written back at all
• Missing a version marker — same

Missing a card URL is the one to watch. Contacts imported before write-back existed never recorded which card was theirs, so FreeITSM does not know where to write. The fix is simply to run an import — every import records it from then on. If this number is not zero, that is why write-back is quietly doing nothing for those people.

---

D016 — CardDAV drift

System → Debug Tools → D016

Answers a different question: "do the two lists still agree?"

It compares every imported person against their card as it stands right now, detail by detail, with both values side by side. It is slower than the other tools because it has to read every card in the book — there is no way to ask a CardDAV server "which of these changed".

When to run it

• Before switching write-back on. Existing drift is exactly what will cause refusals, so it is worth knowing what you are walking into.
• After an import that looked wrong.
• When somebody says a number is out of date and you need to know which side is stale.
• Periodically, if you want to know whether keeping the two in step is worth the trouble at all.

What the output tells you

Section	Meaning
In step	Person and card agree on all five details
Disagreeing	Both values shown, FreeITSM's first, the card's second
No longer on the server	Their card has gone. FreeITSM never deletes anybody — the import marks people as left after the configured number of missed runs
On the server but not here	Usually correct: they are outside the group or tag you chose to import
Missing a card URL	As in D015 — write-back cannot reach these until the next import

An empty value is printed as (empty) rather than left blank, so "they have no mobile" is never confused with "the report ran out of room".

The tally at the bottom is the point

D016 finishes with which details drift most, across everybody.

⭐ That number is genuinely hard to get any other way, and it is the honest evidence for whether two-way sync earns its keep — and for which fields. If the answer turns out to be "phone numbers drift constantly and job titles never do", that tells you something real about how your organisation works, measured rather than guessed.

🔴 Why there is no "fix it" button

Deliberate, and it will stay that way.

Which side is right is a judgement. The card might be stale because nobody has updated it since somebody left; FreeITSM's copy might be stale because an analyst typed a number wrong. A single button that reconciles hundreds of contacts in one direction is precisely how a careful integration turns into a data-loss incident — and, per the asymmetry at the top of this page, in the direction we cannot undo.

⚠️ The trap D016 reveals

Drift is exactly what makes a later write-back get refused. If D016 shows a person disagreeing and you then edit that same detail in FreeITSM, it will not be written — FreeITSM will not overwrite a value it did not last import.

So the order is: import first, then edit.

---

Symptom → where to look

What you are seeing	Start here
"Is it even trying?"	Write log. No rows at all = nothing attempted
Every save says Failed	D015 rung 1 or 2
Every save says Refused	Import first. Then D016 to see how far apart they are
401, and the password is definitely right	The Digest trap. Set authentication back to Automatic
Saves succeed but the card never changes	D015 rung 4 — missing card URLs
Fields are greyed out and won't edit	Write-back is off, or you did not press Save after ticking it
Contacts imported that should not have	You are pointed at the wrong address book, or the scope is set to everything
It worked and now doesn't	Write log — the last successful row tells you when it changed

---

What is deliberately not automatic

Worth stating plainly, because each one is a thing people ask for.

• No scheduled write-back. Changes go when an analyst saves one, never as a sweep.
• No bulk reconcile. See D016 above.
• No deleting. FreeITSM never deletes a contact from your address book under any circumstances.
• No creating. A person created in FreeITSM does not become a new card. Write-back only updates contacts that were imported.
• No portal self-service write-back. A customer correcting their own details in the portal is still refused on an imported contact. That is the GDPR Article 16 case from #133 and it needs a decision about customers writing to your address book, not just wiring.

---

See also

• CardDAV contact sync — the feature, and how to set it up
• CardDAV write-back internals — how it works inside, and why it refuses rather than guesses
• CardDAV import internals — the import half
• CalDAV and CardDAV — the original analysis, and CalDAV, which is not built