apache/seatunnel · error · IllegalArgumentException

Invalid AmazonDocumentDB connection URI in option 'uri'

Error message

Invalid AmazonDocumentDB connection URI in option 'uri'

What it means

parseConnectionString wraps the MongoDB driver's ConnectionString parser: when the 'uri' option is not a valid MongoDB connection string, the driver's IllegalArgumentException is rethrown as "Invalid AmazonDocumentDB connection URI in option 'uri'" with the original cause preserved, attributing the failure to the 'uri' option.

Solutions

  1. Ensure the uri starts with mongodb:// — a bare DocumentDB endpoint is not a valid connection string
  2. URL-encode username and password: escape @ : / ? # % (e.g. p@ss -> p%40ss)
  3. Strip surrounding quotes/whitespace if the value came from an env variable or templating engine
  4. Test the uri with mongosh or the MongoDB ConnectionString parser to see the driver's underlying cause

Example fix

// before
uri = "docdb-cluster.cluster-xxxx.us-east-1.docdb.amazonaws.com:27017"  // no scheme
// after
uri = "mongodb://admin:p%40ss@docdb-cluster.cluster-xxxx.us-east-1.docdb.amazonaws.com:27017/?tls=true&tlsCAFile=rds-ca.crt"
Defensive patterns

Strategy: validation

Validate before calling

// validate the uri shape before submitting the job
function assertValidMongoUri(uri) {
  if (!/^mongodb(\+srv)?:\/\//.test(uri)) {
    throw new Error("uri must start with mongodb:// or mongodb+srv://");
  }
  if (uri !== uri.trim()) {
    throw new Error("uri has surrounding whitespace");
  }
}
assertValidMongoUri(process.env.DOCDB_URI);

Type guard

boolean looksLikeMongoUri(String uri) {
  return uri != null && uri.trim().startsWith("mongodb://");
}

Try / catch

try {
    AmazonDocumentDBConfig config = new AmazonDocumentDBConfig(readonlyConfig);
} catch (IllegalArgumentException e) {
    if (String.valueOf(e.getMessage()).contains("Invalid AmazonDocumentDB connection URI")) {
        // e.getCause() is the driver's original parse error — surface it for the exact offending token
        throw new IllegalArgumentException("Bad 'uri' option: "
            + (e.getCause() != null ? e.getCause().getMessage() : e.getMessage()), e);
    }
    throw e;
}

Prevention

When it happens

Trigger: Job startup where option 'uri' fails new ConnectionString(uri): missing mongodb:// scheme, malformed host list, unparseable options after '?', or illegal characters in username/password (e.g. a raw '@' or ':' in an unencoded password).

Common situations: Special characters in passwords not URL-encoded (very common: @, #, %); missing 'mongodb://' prefix when pasting a raw cluster endpoint; stray quotes or whitespace from env-var templating; copy-paste of an aws docdb endpoint alone, which is not a URI.

Understand the failure class

Background: "Invalid URL" errors: why new URL(), URI.parse, and reqwest::Url reject your string — missing scheme, whitespace, and bad path format — this error's family across 39 libraries.

Related errors

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

Appendix: source

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

        MongoClientSettings.Builder builder =
                MongoClientSettings.builder()
                        .applyConnectionString(connectionString)
                        .retryWrites(false);
        builder.applyToSslSettings(
                sslBuilder -> {
                    sslBuilder.enabled(tls);
                    if (tls) {
                        sslBuilder.context(createSslContext(Paths.get(tlsCaFile)));
                    }
                });
        return builder.build();
    }

    private static ConnectionString parseConnectionString(String uri) {
        try {
            return new ConnectionString(uri);
        } catch (IllegalArgumentException e) {
            throw new IllegalArgumentException(
                    "Invalid AmazonDocumentDB connection URI in option 'uri'", e);
        }
    }

    private static boolean hasRetryWritesEnabled(String uri) {
        int queryStart = uri.indexOf('?');
        if (queryStart < 0 || queryStart == uri.length() - 1) {
            return false;
        }
        String query = uri.substring(queryStart + 1);
        int fragmentStart = query.indexOf('#');
        if (fragmentStart >= 0) {
            query = query.substring(0, fragmentStart);
        }
        for (String parameter : query.split("&")) {
            int separator = parameter.indexOf('=');
            if (separator < 0) {
                continue;

View on GitHub (pinned to cf67b549a7)