Errors
state_optimistic_lock_conflict
409 — the resource was modified concurrently and the update cannot be applied against a stale version.
Last updated
Cause
Matter uses optimistic concurrency control on resources that can be edited by multiple agents in parallel — grants under amendment, board rosters, registered-agent assignments, document drafts. The caller passes the version it last observed, and Matter compares it against the row's current version inside the write transaction. state_optimistic_lock_conflict fires when those versions disagree, meaning another writer has mutated the resource since the caller last read it.
This is not an error in the colloquial sense — it's the system catching a write-after-write race and refusing to silently overwrite. The losing writer is expected to re-read, decide whether their intended change still makes sense, and retry. There is no automatic merge: the platform never invents a resolution where two humans (or agents) made conflicting decisions.
Fix
- Re-fetch the resource. The response includes the new
versionand the new field values. - Diff your intended change against the new state. If your change still makes sense, apply it on top and retry with the new
version. - If the new state already reflects your intent, you have nothing to do — the other writer's update achieved the same goal.
- If the two changes are semantically incompatible, surface the conflict to a human. Two writers wanting different things is a coordination problem, not a retry problem.
Related codes
state_transition_invalid— the resource is in a state that cannot make this transition.validation_idempotency_key_conflict— the same idempotency key was reused with a different body.state_authorisation_required— an authorising Resolution is missing.