apache/seatunnel · warning

Ambiguous timeout on Couchbase write (docId='{}'), attempt={

Error message

Ambiguous timeout on Couchbase write (docId='{}'), attempt={} — will retry from the same position to verify commit status.

What it means

CouchbaseWriter.doFlush detects AmbiguousTimeoutException, meaning the SDK cannot confirm whether a mutation was committed on the server. The writer records the in-flight index and replays from the same position on retry, so a DocumentExistsException on the next attempt can be interpreted as 'already committed' rather than a genuine collision. This warning is informational about a retry, not a failure — unless maxRetries is exhausted.

Source

Thrown at seatunnel-connectors-v2/connector-couchbase/src/main/java/org/apache/seatunnel/connectors/seatunnel/couchbase/sink/CouchbaseWriter.java:610

                                            + " prior ambiguous timeout at index={} — treating as"
                                            + " already committed; skipping.",
                                    unit.docId,
                                    i);
                            ambiguousIndices.remove(i);
                        }
                    }
                    // Advance the cursor only after the write is confirmed (or confirmed-already-
                    // present) so that a failure on the very next row does not skip this one.
                    startFrom = i + 1;
                }
                buffer.clear();
                return;
            } catch (AmbiguousTimeoutException ate) {
                // Record the in-flight index so the next attempt can distinguish a
                // "previously committed" DocumentExistsException from a genuine collision.
                // Do NOT advance startFrom — the next attempt replays from the same position.
                ambiguousIndices.add(startFrom);
                log.warn(
                        "Ambiguous timeout on Couchbase write (docId='{}'), attempt={} — "
                                + "will retry from the same position to verify commit status.",
                        units.get(startFrom).docId,
                        attempt,
                        ate);
                if (attempt >= maxRetries) {
                    throw new CouchbaseConnectorException(
                            CouchbaseConnectorErrorCode.WRITE_RECORDS_FAILED,
                            "Batch write to Couchbase failed after " + maxRetries + " retries",
                            ate);
                }
                attempt++;
                try {
                    TimeUnit.MILLISECONDS.sleep(retryIntervalMs * attempt);
                } catch (InterruptedException ie) {
                    Thread.currentThread().interrupt();
                    throw new CouchbaseConnectorException(
                            CouchbaseConnectorErrorCode.WRITE_RECORDS_FAILED,

View on GitHub (pinned to cf67b549a7)

Solutions

1. No action needed if retries succeed — the writer verifies commit status automatically; check logs for subsequent success
2. Increase SDK/operation timeouts or maxRetries in the sink config if ambiguity happens frequently
3. Investigate network stability and Couchbase cluster health (rebalances, failovers); tune bucket RAM and index settings under load

Example fix

// before (aggressive timeouts)
.timeout(Duration.ofSeconds(2))
// after
.timeout(Duration.ofSeconds(10)) // tolerate latency spikes; writer still replays safely
.maxRetries = 5;

// Pre-check connectivity/bucket health before writing
cluster.bucket(bucketName).waitUntilReady(Duration.ofSeconds(10));

try {
  collection.mutateIn(docId, specs);
} catch (AmbiguousTimeoutException e) {
  // retry same op; treat DocumentExistsException on retry as success (already committed)
}

When it happens

Trigger: A mutation (insert/upsert via docId) times out with an ambiguous outcome — the request reached the server but the ack was lost or the op was still in flight when the timeout fired.

Common situations: High latency or GC pauses between client and Couchbase cluster; network flaps; KV timeouts set too aggressively for workload; heavy cluster load or rebalance in progress.

Understand the failure class

Background: Request timed out: what client-side request timeouts mean across libraries (Request timed out, TIMED_OUT, APITimeoutError) — this error's family across 39 libraries.

• Timeouts: ETIMEDOUT, deadlines, and hung requests — what actually expires when a request times out.

Related errors

• Execute given execution failed after retry <n> times
• Exceeded maxBatchSendAttempts=${maxBatchSendAttempts} withou
• Failed to execute HTTP request to %s after %d attempts
• Retry times must be greater than 0
• Interrupted during retry

AI-assisted analysis of apache/seatunnel@cf67b549a7 (2026-09-10). Data as JSON: /api/errors/45e4b45afce627ae. Report an issue: GitHub.