Sulu optimistic locking version column returns 409 Conflict on retried content writes

Short answer

Sulu does not ship with a built-in server-side idempotency key or request-deduplication layer for content writes. Optimistic locking through the Doctrine version column is the primary concurrency control. When the API returns 409 Conflict, the client-supplied version is stale; the correct response is to fetch the latest resource state, merge your changes, and resubmit with the current version. Blindly reapplying the original payload will overwrite concurrent edits.

Confirmed behavior vs. version-dependent details

Confirmed: Doctrine optimistic locking uses a @Version column on Sulu content documents. A mismatch between the submitted version and the stored version raises an optimistic lock exception.

Version-dependent: The exact exception-to-HTTP mapping can vary across Sulu and Symfony releases. In many standard setups this surfaces as HTTP 409, but if you use a custom controller or an older Sulu version, verify that OptimisticLockException is actually translated to a 409 response rather than a 500 or 400.

Retry pattern for updates

1. Read the current resource and note its version value.
2. Submit your write with that version.
3. If you receive 409, fetch the resource again.
4. Merge your intended changes into the newly fetched state.
5. Resubmit with the updated version.

This read-modify-write loop uses the version as a precondition. It prevents lost updates and avoids duplicate entries because the write remains an update to the same document.

Preventing duplicates on creation

Optimistic locking guards updates, not initial creation. To make retried creates idempotent, use an idempotent HTTP method such as PUT with a client-chosen identifier (for example, a UUID in the path). That way, a retry targets the same resource instead of creating a second one.

Why disabling versioning is not recommended

Turning off the version column removes the 409 response, but it also removes protection against concurrent overwrites. In collaborative editing scenarios, the last writer wins silently, which is usually worse than a conflict error.

Verification

• Inspect the document entity to confirm the Doctrine @Version annotation and its backing column.
• Trigger two concurrent updates with mismatched versions and confirm the API returns 409.
• Review your exception handling configuration to verify the mapping in your specific Sulu release.
• Perform a manual retry after fetching the latest version to confirm the write succeeds without creating a duplicate.

# Locate the version annotation in your document entity (adjust path to your project)
grep -r "@Version" src/Entity/ src/Document/

One diagnostic question

Are you writing through Sulu's standard content API, or through a custom controller? The answer determines whether the 409 mapping is guaranteed or needs explicit configuration.