Next.js Concurrent Edits: Version Checks & Conflict Recovery

Protect edits when several clients read the same record

Two users open version seven of a project. One changes the deadline and saves version eight. The other changes the description and submits the old form, including the original deadline. An unconditional update can silently erase the first change. The same race occurs between browser tabs, imports, background jobs, and administrative tools.

Define which edits may replace earlier values, which may merge, and which require explicit review. For ordinary records with occasional contention, an optimistic version check is a practical starting point: accept an update only if the stored version still matches the version the client edited.

Return an opaque revision with every editable representation

Include a revision in the read response and require it in the mutation request. A monotonic integer is easy to reason about; a robust opaque token can work too. Avoid using a low-resolution timestamp as the only revision because multiple writes can share it.

Validate the expected revision, allowed fields, and payload size on the server. Resolve identity and tenant context before touching the record. All writers—including imports and maintenance jobs—must participate in the version policy, or they can bypass the protection.

Compare the revision inside the database write

A read followed by an unconditional update still races. Put the revision predicate in the update itself and increment the revision in that same statement. Check the affected row count before acknowledging success.

-- Illustrative parameterized update
UPDATE projects
SET description = $1, version = version + 1
WHERE id = $2
  AND tenant_id = $3
  AND version = $4
RETURNING id, description, version;

If no row changes, perform an authorized lookup to distinguish a stale revision from a missing or inaccessible resource according to your API policy. Do not disclose another tenant's record while diagnosing the mismatch. Commit associated domain events and audit evidence within the same transactional boundary.

Return enough context for safe recovery

Use a documented conflict response with a stable error code. A body-based revision contract can use HTTP 409; an explicit HTTP conditional-request contract should follow its precondition semantics. Keep the behavior consistent across clients.

Return or fetch the latest authorized representation and revision. Preserve the local draft, explain which record changed, and offer review or reload. Do not automatically retry the old full payload with the new revision: that would approve the overwrite the version check just prevented.

For the surrounding route contract, see our Next.js API route guide.

Use the original snapshot to evaluate field-level changes

A three-way comparison considers the original values, the local draft, and the latest server values. If only the local client changed a field, its edit may be applied. If only the server changed it, preserve the server value. If both changed it differently, ask for a decision.

Independent fields are not always independent business decisions. A start date and end date can violate an invariant even when each editor touched a different field. Validate the merged candidate as a complete domain change and submit it against the latest revision. Another concurrent edit can still produce a new conflict.

Express intent for counters and workflow transitions

For a counter, send an increment operation rather than a replacement value computed from a stale read. For an approval, express the allowed transition and enforce its current-state predicate. For capacity or balance constraints, use a transactional domain operation that validates the shared invariant.

Keep transactions short. Multi-record invariants may require suitable isolation, locks, or another database-specific strategy in addition to a single record revision. A browser editing session should not hold a database lock while a user considers a form.

Handle an uncertain save without repeating its effects

A request may commit successfully and then lose its response. Retrying with the old revision can look like a conflict even though the client's own update succeeded. Pair revision checks with a stable mutation operation ID when the workflow needs safe retries.

Store the operation result with the write and return it for an authorized repeat. Bind the operation ID to actor, tenant, action, and payload so it cannot authorize a different request. Version checks protect against competing edits; idempotency protects against repeated delivery of the same edit.

Keep drafts and conflict decisions visible

Pause autosave when a conflict appears, retain the unsaved draft, and show the latest values alongside the user's proposed changes. Keep keyboard focus stable and provide clear actions for review, discard, or resubmit. Do not communicate conflict only through a toast that disappears.

Scope optimistic cache updates to the relevant record and revert them carefully when a save fails. Live change hints can warn that a record changed, but server-side revision enforcement remains necessary. Our React autosave guide covers draft management and client recovery in more detail.

Test competing writers at the commit boundary

Have two clients read the same revision, then submit different updates concurrently. Verify that only one commits and the other retains its draft with a conflict response. Test edits from imports and workers, deleted records, revoked permissions, repeated requests, and ambiguous response loss.

Test three-way merge rules with cross-field invariants, and trigger another edit during conflict review. Track conflict frequency, resolution outcomes, repeated mutation IDs, and affected-row mismatches. Log safe record references and revisions without copying sensitive draft content.

Concurrent editing checklist