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.

Invest now in Acorns!!! 🚀
Join Acorns and get your $5 bonus!

Acorns is a micro-investing app that automatically invests your "spare change" from daily purchases into diversified, expert-built portfolios of ETFs. It is designed for beginners, allowing you to start investing with as little as $5. The service automates saving and investing. Disclosure: I may receive a referral bonus.

Invest now!!! Get Free equity stock (US, UK only)!

Use Robinhood app to invest in stocks. It is safe and secure. Use the Referral link to claim your free stock when you sign up!.

The Robinhood app makes it easy to trade stocks, crypto and more.

Webull! Receive free stock by signing up using the link: Webull signup.