> ## Documentation Index
> Fetch the complete documentation index at: https://docs.pocketsync.dev/llms.txt
> Use this file to discover all available pages before exploring further.

# Conflict resolution

> How PocketSync handles conflicts

In distributed systems like PocketSync, conflicts occur when multiple devices modify the same database record without immediate synchronization. The MergeEngine component is responsible for detecting these conflicts and resolving them according to configurable strategies.

```mermaid theme={null}
flowchart TD
    LC[Local Changes]
    RC[Remote Changes]
    SW[SyncWorker]
    ME[MergeEngine]
    DB[Database]
    App[Application]

    LC --> SW
    RC --> SW
    SW --> ME

    subgraph "Conflict Resolution Process"
        ME
    end

    ME -->|Resolved Changes| DB
    ME -->|Conflict Notification| App
```

## Conflict detection

A conflict is detected when both the local device and the server have changes for the same record. The MergeEngine identifies conflicts by grouping changes by their unique record identifier (table name + record ID).

```mermaid theme={null}
flowchart TB
    subgraph "Changes from Different Sources"
        LC[Local Changes]
        RC[Remote Changes]
    end
    
    subgraph "Conflict Detection"
        Group[Group by record ID]
        Check{Multiple changes<br>for same record?}
        Conflict[Conflict Detected]
        NoConflict[No Conflict]
        Resolution[Apply Resolution Strategy]
        Direct[Apply Change Directly]
    end
    
    LC --> Group
    RC --> Group
    Group --> Check
    Check -->|Yes| Conflict
    Check -->|No| NoConflict
    Conflict --> Resolution
    NoConflict --> Direct
```

## Conflict resolution strategies

PocketSync supports four different strategies for resolving conflicts, defined in ConflictResolutionStrategy:

| Strategy                  | Description                                 | Use Case                                                         |
| ------------------------- | ------------------------------------------- | ---------------------------------------------------------------- |
| `lastWriteWins` (Default) | Most recent change based on timestamp wins  | General purpose, when recent changes are typically more relevant |
| `serverWins`              | Remote changes always take precedence       | When the server is considered the source of truth                |
| `clientWins`              | Local changes always take precedence        | When local user actions should override server changes           |
| `custom`                  | Uses a developer-provided resolver function | Complex scenarios requiring application-specific logic           |

## Best practices

When working with PocketSync's conflict resolution:

* Choose the appropriate strategy for your application's needs
* Use custom resolution for complex business logic requirements

## Limitations

The current conflict resolution system has these limitations:

* Conflicts are resolved at the record level, not at the field level
* The default last-write-wins strategy depends on accurate device timestamps
* Conflicts between delete and update operations always follow the configured strategy

For more advanced conflict resolution needs, see [custom conflict resolution](/advanced/custom-conflict-resolution).