{"record":{"id":"90dccc0f0300b6f9","repo":"apache/seatunnel","slug":"amazondocumentdb-option-tls-ca-file-is-required","errorCode":null,"errorMessage":"AmazonDocumentDB option 'tls_ca_file' is required when TLS is enabled","messagePattern":"AmazonDocumentDB option 'tls_ca_file' is required when TLS is enabled","errorType":"validation","errorClass":"IllegalArgumentException","httpStatus":null,"severity":"error","filePath":"seatunnel-connectors-v2/connector-amazondocumentdb/src/main/java/org/apache/seatunnel/connectors/seatunnel/amazondocumentdb/config/AmazonDocumentDBConfig.java","lineNumber":186,"sourceCode":"    private static String decodeUriParameter(String value) {\n        try {\n            return URLDecoder.decode(value, StandardCharsets.UTF_8.name());\n        } catch (UnsupportedEncodingException e) {\n            throw new IllegalStateException(\"UTF-8 must be supported\", e);\n        }\n    }\n\n    private static String requireNonBlank(String value, String optionName) {\n        if (value == null || value.trim().isEmpty()) {\n            throw new IllegalArgumentException(\n                    \"AmazonDocumentDB option '\" + optionName + \"' must not be blank\");\n        }\n        return value.trim();\n    }\n\n    private static void validateTlsCaFile(String tlsCaFile) {\n        if (tlsCaFile == null) {\n            throw new IllegalArgumentException(\n                    \"AmazonDocumentDB option 'tls_ca_file' is required when TLS is enabled\");\n        }\n        Path path = Paths.get(tlsCaFile);\n        if (!Files.isRegularFile(path) || !Files.isReadable(path)) {\n            throw new IllegalArgumentException(\n                    \"AmazonDocumentDB TLS CA bundle is not a readable file: \" + tlsCaFile);\n        }\n    }\n\n    private static void validateBsonDocument(String value, String optionName) {\n        try {\n            BsonDocument.parse(value);\n        } catch (RuntimeException e) {\n            throw new IllegalArgumentException(\n                    \"AmazonDocumentDB option '\"\n                            + optionName\n                            + \"' must be a valid BSON/JSON document\",\n                    e);","sourceCodeStart":168,"sourceCodeEnd":204,"githubUrl":"https://github.com/apache/seatunnel/blob/cf67b549a7a6c35fa0beb12d83c62892427ea919/seatunnel-connectors-v2/connector-amazondocumentdb/src/main/java/org/apache/seatunnel/connectors/seatunnel/amazondocumentdb/config/AmazonDocumentDBConfig.java#L168-L204","documentation":"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.","triggerScenarios":"Configuring use_tls/tls=true (or equivalent TLS option) without providing tls_ca_file, so the option value is null when validateTlsCaFile runs.","commonSituations":"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.","solutions":["Download the AWS CA bundle (rds-ca global-bundle.pem) and set tls_ca_file = \"/path/global-bundle.pem\".","Verify the exact option key is tls_ca_file, not a camelCase or hyphenated variant.","If TLS is genuinely not needed, disable the TLS option so validation is skipped."],"exampleFix":"// before\nuri = \"mongodb://user:pass@docdb:27017/?tls=true\"\n// after\nuri = \"mongodb://user:pass@docdb:27017/?tls=true\"\ntls_ca_file = \"/opt/certs/global-bundle.pem\"","handlingStrategy":"validation","validationCode":"boolean tls = cfg.getBoolean(USE_TLS);\nString caFile = tls ? cfg.getString(TLS_CA_FILE) : null;\nif (tls && (caFile == null || caFile.isBlank())) {\n    throw new IllegalArgumentException(\"tls_ca_file must be set when TLS is enabled\");\n}","typeGuard":null,"tryCatchPattern":null,"preventionTips":["Always pair TLS=true with a downloaded AWS global-bundle.pem in the same config change.","Keep the bundle path in a shared, documented location on all nodes.","Review connector option keys against docs to avoid misspelling that silently leaves the option null."],"tags":["tls","configuration","amazondocumentdb"],"backgroundTag":"missing-required-config-field","analyzedSha":"cf67b549a7a6c35fa0beb12d83c62892427ea919","analyzedAt":"2026-09-10T21:44:55.265Z","contentChangedAt":"2026-09-10T21:44:55.265Z","schemaVersion":2},"datasetVersion":"2026-09-14T05:17:10.506Z"}