apache/seatunnel · error · IllegalArgumentException

AmazonDocumentDB does not support retryable writes; remove '

Error message

AmazonDocumentDB does not support retryable writes; remove 'retryWrites=true' from option 'uri' or set it to false

What it means

Amazon DocumentDB does not support MongoDB retryable writes. AmazonDocumentDBConfig inspects the 'uri' option via hasRetryWritesEnabled and throws IllegalArgumentException when retryWrites is enabled, because writes would otherwise fail at runtime against DocumentDB. The error tells you to remove retryWrites=true or set it to false in the URI.

Source

Thrown at seatunnel-connectors-v2/connector-amazondocumentdb/src/main/java/org/apache/seatunnel/connectors/seatunnel/amazondocumentdb/config/AmazonDocumentDBConfig.java:99

        this.projection =
                config.getOptional(AmazonDocumentDBSourceOptions.PROJECTION)
                        .map(String::trim)
                        .filter(value -> !value.isEmpty())
                        .orElse(null);
        this.fetchSize = config.get(AmazonDocumentDBSourceOptions.FETCH_SIZE);
        this.schema =
                config.getOptional(ConnectorCommonOptions.SCHEMA)
                        .map(ReadonlyConfig::fromMap)
                        .map(ReadonlyConfig::toConfig)
                        .orElse(null);

        ConnectionString connectionString = parseConnectionString(uri);
        if (connectionString.getCredential() == null) {
            throw new IllegalArgumentException(
                    "AmazonDocumentDB option 'uri' must include authentication credentials");
        }
        if (hasRetryWritesEnabled(uri)) {
            throw new IllegalArgumentException(
                    "AmazonDocumentDB does not support retryable writes; remove 'retryWrites=true' from option 'uri' or set it to false");
        }
        if (tls) {
            validateTlsCaFile(tlsCaFile);
        }
        validateBsonDocument(matchQuery, "match.query");
        if (projection != null) {
            validateBsonDocument(projection, "match.projection");
        }
    }

    /**
     * Builds driver settings with DocumentDB-safe overrides.
     *
     * <p>The URI is applied first and {@code retryWrites(false)} second deliberately: the latter
     * must win over both driver defaults and any URI option. TLS uses a connector-local {@link
     * SSLContext} built from the configured CA bundle instead of mutating the JVM-global trust
     * store, which would affect unrelated connectors running in the same process.

View on GitHub (pinned to cf67b549a7)

Solutions

1. Remove retryWrites=true from the uri, or explicitly add retryWrites=false
2. Replace the Atlas-copied connection string with one built from your DocumentDB cluster endpoint
3. Audit config templates/secret managers that append retryWrites=true to Mongo URIs and exclude it for DocumentDB

Example fix

// before
uri = "mongodb://admin:pass@docdb.cluster.amazonaws.com:27017/?retryWrites=true"
// after
uri = "mongodb://admin:pass@docdb.cluster.amazonaws.com:27017/?retryWrites=false"

// reject retryWrites before job submission
function assertNoRetryWrites(uri) {
  const q = uri.split('?')[1] || '';
  for (const kv of q.split('&')) {
    const [k, v] = kv.split('=');
    if (k === 'retryWrites' && v !== 'false') {
      throw new Error("DocumentDB: remove retryWrites=true from uri or set retryWrites=false");
    }
  }
}
assertNoRetryWrites(config.uri);

boolean retryWritesDisabled(String uri) {
  int q = uri.indexOf('?');
  if (q < 0) return true;
  for (String p : uri.substring(q + 1).split("&")) {
    if (p.startsWith("retryWrites=")) return p.substring("retryWrites=".length()).equalsIgnoreCase("false");
  }
  return true;
}

try {
    AmazonDocumentDBConfig config = new AmazonDocumentDBConfig(readonlyConfig);
} catch (IllegalArgumentException e) {
    if (String.valueOf(e.getMessage()).contains("retryable writes")) {
        throw new IllegalArgumentException("Replace the uri with one that has retryWrites=false (Atlas default URIs are not valid for DocumentDB)", e);
    }
    throw e;
}

When it happens

Trigger: Job startup where the 'uri' option contains 'retryWrites=true' (the default in many MongoDB connection strings copied from Atlas or framework templates), triggering the hasRetryWritesEnabled check in the constructor.

Common situations: Copying a MongoDB Atlas URI (Atlas appends retryWrites=true by default) and reusing it for DocumentDB; deploy templates that inject retryWrites=true into all Mongo URIs; legacy config carried over from a real MongoDB migration.

Understand the failure class

Background: "Invalid value" and "allowed values are" config errors: what your library rejected and how to fix it — this error's family across 41 libraries.

Related errors

• AmazonDocumentDB option 'uri' must include authentication cr
• Invalid AmazonDocumentDB connection URI in option 'uri'
• AmazonDocumentDB option '' must not be blank
• AmazonDocumentDB option 'tls_ca_file' is required when TLS i
• COMMON-17

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