How does CouchDB handle replication conflicts and what strategies exist to resolve them?

A replication conflict in CouchDB occurs when two nodes have independently updated the same document (same _id) and neither update knew about the other. This is the normal result of multi-master or offline-sync workflows — it is not an error, it is an expected state that the application must handle.

CouchDB stores both conflicting revisions in the database. The document is still readable via its _id, but one revision is designated the winning revision (see Q28 for the algorithm). You can see all conflicting revisions by requesting ?conflicts=true:

# Detect a conflict
curl "http://localhost:5984/mydb/doc1?conflicts=true"
# {
#   "_id":"doc1","_rev":"3-winner...","name":"Alice",
#   "_conflicts":["3-loser..."]
# }

# Fetch the losing revision
curl "http://localhost:5984/mydb/doc1?rev=3-loser..."

# Resolution strategy: pick winning revision, DELETE the losing one
curl -X DELETE "http://localhost:5984/mydb/doc1?rev=3-loser..."

# OR: merge both and save merged version, then DELETE loser
curl -X PUT http://localhost:5984/mydb/doc1 \
  -d '{"_rev":"3-winner...","name":"Alice Smith","merged":true}'
curl -X DELETE "http://localhost:5984/mydb/doc1?rev=3-loser..."

Common resolution strategies:

• Last-write-wins — keep the winning revision (already done automatically), delete losers. Simple but may discard valid changes.
• Application-level merge — read both revisions, merge fields using domain logic (e.g., take the higher stock count), write the merged result as the new winning revision, delete the loser.
• Conflict-free design — model data to avoid conflicts: use separate documents per event (append-only log) instead of updating a shared document; use CouchDB's _local documents for per-device state that does not replicate.