apache/seatunnel · error · IllegalArgumentException

AmazonDocumentDB option '' must not be blank

Error message

AmazonDocumentDB option '' must not be blank

What it means

AmazonDocumentDBConfig.requireNonBlank validates that a user-supplied connector option (uri, database, collection, etc.) is neither null nor whitespace-only. It throws IllegalArgumentException during config parsing when a required option resolves to blank. This fails fast at job startup rather than producing an obscure connection error later.

Source

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

            String value = decodeUriParameter(parameter.substring(separator + 1));
            if ("retryWrites".equalsIgnoreCase(key) && "true".equalsIgnoreCase(value)) {
                return true;
            }
        }
        return false;
    }

    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) {

View on GitHub (pinned to cf67b549a7)

Solutions

1. Set the option to a non-blank value in the SeaTunnel config file (e.g. database = "mydb").
2. Check the exact option key spelling against AmazonDocumentDB documented options.
3. If using env substitution, verify the environment variable is exported and non-empty.

Example fix

// before
database = ""
// after
database = "orders"

String uri = cfg.getOptionalString(URI).orElse("");
if (uri.trim().isEmpty()) {
    throw new IllegalArgumentException("uri must not be blank before building AmazonDocumentDBConfig");
}

When it happens

Trigger: Calling AmazonDocumentDBConfig with a required option (e.g. uri, database, collection) whose value is null, "", or only whitespace (" ").

Common situations: HOCON/YAML config has an empty value like `database = ""`; an env-var placeholder like ${DB_NAME} resolved to empty; a typo in the option name so the default blank value is used.

Understand the failure class

Background: "must not be empty", "cannot be empty" — required-field validation errors across open-source libraries — this error's family across 41 libraries.

Related errors

• Condition operator must not be null
• AmazonDocumentDB option 'tls_ca_file' is required when TLS i
• AmazonDocumentDB option '' must be a valid BSON/JSON documen
• FIELD_NOT_IN_TABLE
• CONFIG_VALIDATION_FAILED

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