apache/seatunnel · error · IllegalArgumentException

AmazonDocumentDB option 'tls_ca_file' is required when TLS i

Error message

AmazonDocumentDB option 'tls_ca_file' is required when TLS is enabled

What it means

When TLS is enabled for the Amazon DocumentDB connection, validateTlsCaFile requires the tls_ca_file option to be set. Because DocumentDB uses a private CA, the driver needs a trust bundle; a null tls_ca_file with TLS on throws IllegalArgumentException immediately during config validation.

Source

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

    private static String decodeUriParameter(String value) {
        try {
            return URLDecoder.decode(value, StandardCharsets.UTF_8.name());
        } catch (UnsupportedEncodingException e) {
            throw new IllegalStateException("UTF-8 must be supported", e);
        }
    }

    private static String requireNonBlank(String value, String optionName) {
        if (value == null || value.trim().isEmpty()) {
            throw new IllegalArgumentException(
                    "AmazonDocumentDB option '" + optionName + "' must not be blank");
        }
        return value.trim();
    }

    private static void validateTlsCaFile(String tlsCaFile) {
        if (tlsCaFile == null) {
            throw new IllegalArgumentException(
                    "AmazonDocumentDB option 'tls_ca_file' is required when TLS is enabled");
        }
        Path path = Paths.get(tlsCaFile);
        if (!Files.isRegularFile(path) || !Files.isReadable(path)) {
            throw new IllegalArgumentException(
                    "AmazonDocumentDB TLS CA bundle is not a readable file: " + tlsCaFile);
        }
    }

    private static void validateBsonDocument(String value, String optionName) {
        try {
            BsonDocument.parse(value);
        } catch (RuntimeException e) {
            throw new IllegalArgumentException(
                    "AmazonDocumentDB option '"
                            + optionName
                            + "' must be a valid BSON/JSON document",
                    e);

View on GitHub (pinned to cf67b549a7)

Solutions

1. Download the AWS CA bundle (rds-ca global-bundle.pem) and set tls_ca_file = "/path/global-bundle.pem".
2. Verify the exact option key is tls_ca_file, not a camelCase or hyphenated variant.
3. If TLS is genuinely not needed, disable the TLS option so validation is skipped.

Example fix

// before
uri = "mongodb://user:pass@docdb:27017/?tls=true"
// after
uri = "mongodb://user:pass@docdb:27017/?tls=true"
tls_ca_file = "/opt/certs/global-bundle.pem"

boolean tls = cfg.getBoolean(USE_TLS);
String caFile = tls ? cfg.getString(TLS_CA_FILE) : null;
if (tls && (caFile == null || caFile.isBlank())) {
    throw new IllegalArgumentException("tls_ca_file must be set when TLS is enabled");
}

When it happens

Trigger: Configuring use_tls/tls=true (or equivalent TLS option) without providing tls_ca_file, so the option value is null when validateTlsCaFile runs.

Common situations: User enables TLS following AWS docs but forgets to download global-bundle.pem; config copied from a non-TLS example; option key misspelled (e.g. tls-ca-file) so the real option stays null.

Understand the failure class

Background: "is required", "must be set", "missing required field": configuration validation errors across open-source libraries — this error's family across 36 libraries.

• SSL/TLS and certificate errors — how TLS handshakes and certificate validation fail.

Related errors

• AmazonDocumentDB option '' must not be blank
• AmazonDocumentDB TLS CA bundle is not a readable file:
• Failed to configure TLS settings
• RABBITMQ-09
• prepare method is not supported

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