neighbourhoodie-nnh-logo

Conflict Resolution in CouchDB with Fauxton posted Wednesday, October 15, 2025 by The Neighbourhoodie Team CouchDBDataSync

One of the key aspects of CouchDB is how it handles concurrent updates. It is built for replication and offline-first or local-first use cases where multiple users and devices edit the same document independently and sync back their changes later. Instead of silently discarding a user’s changes when two users edit the same document, CouchDB keeps track of the conflicts: situations where two or more versions of a document exist simultaneously.

And what’s truly unique about CouchDB is that a conflict does not corrupt data or break replication processes. It allows the users to decide which version of the changed data is ‘correct’. CouchDB even let’s you do this with its own UI called Fauxton.

Some Methods for Handling Conflicts

Last-write-wins (LWW) behaviour and conflict-free replicated data types (CRDTs) are two examples of ways apps can handle conflicts that we’ll briefly look at.

In a LWW scenario you, as a user, don’t get confronted with decisions about which change to keep when conflicts arise. The app will simply save and store the most recently performed change, determined via timestamp or versioning. Preceding changes are discarded.

CRDTs handle conflicts automatically by merging data modifications from multiple replicas into a consistent state. While the pitfalls may not be as apparent at first glance as with LWW, there are limitations to algorithmic conflict-handling.

Luckily, CouchDB is prepared to handle exactly these limitations and ensure data reliability: CouchDB’s Fauxton UI provides the most durable solution to tricky local-first conflict resolution scenarios.

How CouchDB Chooses Winners

When CouchDB encounters conflicting revisions of documents, instead of merging them it chooses a deterministic winner. This is chosen based on a deterministic and arbitrary algorithm. The revision ID with the longest history or highest sort order is chosen. Importantly, this does not mean the winner is the latest or the best edit, it is simply the result of CouchDB’s deterministic conflict resolution rule. This ensures that any CouchDB node chooses the same winning revision without having to coordinate with other nodes and minimising network issues.

Only the winner is shown when you fetch the document, normally GET /{db}/{docid}. Other conflicting revisions are stored in the database until explicitly resolved. To view the full set of conflicting revisions, query with GET /db/test?conflicts=true.

Conflicts in Fauxton

From CouchDB version 2.2.0 and above, Mango queries can be used to retrieve and view documents with conflicts. Then you can either choose to display the conflicts to the user or merge and write back the merged version to the database.

These can be performed using curl but a more user friendly way to do it is via Fauxton. Fauxton is CouchDB’s web-based administration interface which provides visual tools to view and resolve conflicts.

Viewing Conflicts

In the Documents section open any document, and if it has conflicts you’ll see a Conflicts button in the document view. Clicking this button reveals all the conflicting revisions of the document.

This cropped screenshot shows the Fauxton navigation and toolbar, where, under “Database”, users can access with the conflicts interface via a “Conflicts” button.

The conflicts interface shows the server-selected revision alongside the conflicting revision, and provides the user with the option to “Select as Winner” and “Delete Other Conflicts”

When working with large databases, manually opening each document to check for conflicts is impractical. That’s where the Document list view comes in handy.

You can click on the Table button to show the list view of the documents and configure the column to display _conflicts information. This will show you which documents currently have conflicts without needing to open them individually. It’s a helpful feature when resolving multiple conflicts. Please note the _conflicts option will show in the dropdown only if there is at least one document with conflict.

This cropped screenshot shows the Fauxton UI where, under “All Documents”, when “Table” is selected, a column for _conflicts can be added via a drop-down

Resolving Conflicts

In Fauxton, ‘Select as Winner’ is the same as deciding which revision you want to keep and then delete the others.

The screenshot shows a dialog called “Solve Conflicts” which asks “Do you want to delete all conflicting revisions for this document?” The user can “Delete Revisions” with the primary button, “Cancel”, and check a box to decline being shown the message again

In the metadata section for the selected “winning” of the conflicting revisions, the “Value” column now shows {"rev": "2-b"} for the document

Best Practices

  • Check for conflicts regularly: use conflicts=true queries or enable the _conflicts column in Fauxton to get quick views of the data
  • Design conflict resolution strategies in your app: this will allow conflicts to be resolved easily as they arise.
  • Document your conflict resolution rules: whether you display it to the user to choose or you resolve conflict based on certain field values, document them.

Conflicts in CouchDB are not bugs that have to be scary 👻! They are a deliberate design choice that ensures data integrity in distributed systems. Fauxton makes it wonderfully simple to visualise them, pick winners, and resolve issues easily.

Check out our in-depth tutorial for a multi-user Kanban board with CouchDB and Svelte to get more ideas about manual and automatic conflict handling, plus see how conflicts can be prevented.

« Back to the blog post overview
og-image-preview