apache/seatunnel · error · IllegalArgumentException

AmazonDocumentDB option '' must be a valid BSON/JSON documen

Error message

AmazonDocumentDB option '' must be a valid BSON/JSON document

What it means

validateBsonDocument parses option values that must be BSON/JSON documents (e.g. match query, projection, aggregate pipeline stages) with BsonDocument.parse. If parsing throws, it wraps the cause in an IllegalArgumentException stating which option is invalid. This surfaces malformed JSON at config time instead of inside the Mongo driver.

Source

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

    }

    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);
        }
    }

    /** Builds an isolated trust context from every X.509 certificate in the supplied CA bundle. */
    private static SSLContext createSslContext(Path caBundlePath) {
        try (InputStream inputStream = Files.newInputStream(caBundlePath)) {
            CertificateFactory certificateFactory = CertificateFactory.getInstance("X.509");
            Collection<? extends Certificate> certificates =
                    certificateFactory.generateCertificates(inputStream);
            if (certificates.isEmpty()) {
                throw new IllegalArgumentException(
                        "AmazonDocumentDB TLS CA bundle contains no certificates: " + caBundlePath);
            }

View on GitHub (pinned to cf67b549a7)

Solutions

1. Validate the option value is strict JSON: quote keys with double quotes, use double-quoted strings, no trailing commas.
2. Test with `BsonDocument.parse(...)` or a JSON linter before deploying.
3. If a top-level array is needed (e.g. pipeline), put it under a document key or check whether the connector expects a document, not an array.

Example fix

// before
match_query = "{'status': 'active',}"  // single quotes + trailing comma
// after
match_query = "{\"status\": \"active\"}"

try {
    org.bson.BsonDocument.parse(matchQuery);
} catch (RuntimeException e) {
    throw new IllegalArgumentException("match query is not valid BSON/JSON: " + e.getMessage(), e);
}

try {
    BsonDocument.parse(value);
} catch (IllegalArgumentException e) {
    log.error("Invalid BSON/JSON option value", e);
    // surface to user, fail config load
}

When it happens

Trigger: An option such as the match/filter query contains invalid JSON: unquoted keys, single quotes, trailing commas, or a non-document value (array/scalar).

Common situations: Copy-pasted filter with single quotes or unquoted keys; template placeholders (e.g. ${date}) left unexpanded producing `{"ts": {time}}`; a JSON array passed where a top-level document is expected.

Understand the failure class

Background: "Invalid JSON response" and "Failed to parse response" errors: when an API answers 200 but the body isn't the JSON your library expected — this error's family across 28 libraries.

Related errors

• Condition operator must not be null
• AmazonDocumentDB option '' must not be blank
• FIELD_NOT_IN_TABLE
• CONFIG_VALIDATION_FAILED
• CommonErrorCodeDeprecated.UNSUPPORTED_OPERATION

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