Conflict Resolution
How Sync Gateway resolves document conflicts during synchronization
Related Sync topics: Conflict Resolution | Bootstrap Configuration
Overview
Starting with Sync Gateway 4.0+, the default conflict resolution strategy has changed from Most Write Wins (MWW) to Last Write Wins (LWW):
-
Most Write Wins: The source (device/cluster) with more changes to a document wins in conflicts
-
Last Write Wins: Timestamp-based resolution where the document with the latest timestamp wins
This fundamental change aligns with the shift from revision trees to version vectors and enables better consistency across distributed deployments.
Conflicts are automatically resolved [1] using deterministic algorithms that verify consistency across all participating nodes.
Conflict Resolution Strategies
Last Write Wins (Default in 4.0+)
Last Write Wins uses hybrid logical clock timestamp comparison to resolve conflicts deterministically. The document with the latest timestamp wins the conflict, with timestamps generated using version vectors and Hybrid Logical Vectors (HLV) for accurate ordering.
This strategy provides:
-
Deterministic conflict resolution across all clusters
-
Consistency with XDCR timestamp-based conflict resolution
-
Better support for active-active deployments
-
Alignment with modern distributed systems practices
Timestamp accuracy depends on clock synchronization. XDCR deployments expect server clocks to remain synchronized (see Time Synchronization). Mobile devices may have unsynchronized clocks, but each Couchbase Lite instance maintains its own Hybrid Logical Clock that captures relative time, providing sufficient accuracy for conflict resolution.
Most Write Wins (Versions < 4.0+)
Sync Gateway uses Most Write Wins conflict resolution in the following scenarios:
-
Sync Gateway 4.0+ replicating with Couchbase Lite < 4.0+ clients
-
Sync Gateway 4.0+ replicating with Sync Gateway < 4.0+ instances via Inter-Sync Gateway Replication
-
Cross-version compatibility scenarios
In these cases, the document with the most revisions wins the conflict, maintaining backward compatibility.
| For Sync Gateway versions less than 4.0+, Most Write Wins is the default behavior. See Upgrading Sync Gateway for upgrade instructions. |
XDCR Integration
For active-active deployments using XDCR with Sync Gateway 4.0+, configure your Couchbase Server buckets to use Timestamp-based conflict resolution to match Sync Gateway’s Last Write Wins behavior.
| This configuration has significant constraints: |
-
The conflict resolution strategy must be chosen when the bucket is created and cannot be changed later
-
Both sides of an XDCR replication must have matching conflict resolution strategies
-
This is only feasible for new deployments, not existing ones
For detailed information about configuring XDCR conflict resolution, see Choosing a Conflict Resolution Policy.
When properly configured, this ensures consistent conflict resolution across: * Sync Gateway ↔ Couchbase Lite replication * XDCR bucket-to-bucket replication * Mixed mobile and server-side application scenarios
See BI-directional XDCR with Mobile Clusters for detailed configuration guidance.
Platform-Specific Documentation
The Couchbase Lite SDK guides describe how automatic conflict resolution works on each platform:
Swift | Java | Java (Android) | C# | Objective-C