Transitioning Couchbase Java SDK 3.x retry behavior to default idempotent mutations

Short answer

No — making every retried mutation idempotent by default would be a breaking change, not a safety improvement. In Couchbase Java SDK 3.x, the built-in BestEffortRetryStrategy deliberately retries only operations the SDK knows are idempotent (reads, sub-document reads) or that the application explicitly marks as retryable. Mutations such as upsert, insert, replace, and non-upsert mutateIn are treated as non-idempotent, so a transient network error does not trigger an automatic resend. That default is what protects you from duplicate writes today.

One caveat: this reflects established SDK 3.x behavior as generally documented. Verify against the RetryStrategy javadoc and release notes for your exact minor version, since defaults can change across releases.

Why a default-idempotent mode would be dangerous

Idempotency is a property of the operation, not the transport. An append to a list field, a counter increment, or a blind upsert executed twice produces a different result than executed once. The SDK cannot know your semantics, so it cannot safely decide for you. If the default flipped:

• CAS-based optimistic locking would silently break. Today, a retried mutation carrying a stale CAS fails with a CAS mismatch, which is exactly the "lost update" signal applications depend on. If the SDK retried blindly — or worse, if retries were treated as safe regardless of CAS — concurrent-modification detection would produce confusing behavior: either spurious CAS failures surfaced differently, or duplicate application of the change.
• Write amplification. Every ambiguous timeout (where the server may already have applied the mutation) would generate a second write attempt, increasing load precisely during network instability.
• Retry storms. During partitions or failovers, broadly-idempotent retries multiply traffic against an already degraded cluster. Timeout budgets and maxRetries would need retuning across every existing deployment.
• Latency regression. Operations that currently fail fast and let the application decide would instead burn time in retry loops.

The migration path that actually works

You don't need the SDK to change its default; you need to tell it which of your mutations are safe to retry. The 3.x RetryStrategy interface lets you decide per request:

1. Keep your CAS logic unchanged. Read with get, mutate with the returned CAS. A retry that arrives with a stale CAS still fails cleanly — no duplicate write.
2. Implement a custom RetryStrategy that returns retry-approval only for operations you know are safe: mutations carrying a CAS from a prior read, or mutateIn calls using upsert semantics on a specific path. Check the RetryReason (e.g., node unreachable, timeout) and decline permanent errors.
3. Keep the strategy stateless and thread-safe — it is shared across requests.
4. Verify with fault injection. Use a proxy such as Toxiproxy to drop the connection mid-mutation: confirm the default strategy does not retry a bare mutation, then confirm your custom strategy retries a CAS-carrying mutation exactly once and that a concurrent modification still surfaces as a CAS mismatch rather than a silent duplicate.

Bottom line

Default-idempotent retries would trade a rare, visible failure (an unretried transient error the app must handle) for an invisible one (duplicate writes and defeated CAS checks) across all existing code. The burden belongs with the application, and the SDK already provides the hook — a scoped custom RetryStrategy — to shift that burden only where your semantics genuinely allow it.