apache/seatunnel · error · IllegalArgumentException

AmazonDocumentDB option 'uri' must include authentication cr

Error message

AmazonDocumentDB option 'uri' must include authentication credentials

What it means

AmazonDocumentDBConfig validates the 'uri' option at construction: it parses the connection string and requires embedded authentication credentials (username:password). A URI without a credential component makes ConnectionString.getCredential() return null, and the constructor rejects it with IllegalArgumentException because the connector relies on credentials embedded in the URI.

Source

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

                        .map(String::trim)
                        .filter(value -> !value.isEmpty())
                        .orElse(null);
        this.matchQuery = config.get(AmazonDocumentDBSourceOptions.MATCH_QUERY);
        this.projection =
                config.getOptional(AmazonDocumentDBSourceOptions.PROJECTION)
                        .map(String::trim)
                        .filter(value -> !value.isEmpty())
                        .orElse(null);
        this.fetchSize = config.get(AmazonDocumentDBSourceOptions.FETCH_SIZE);
        this.schema =
                config.getOptional(ConnectorCommonOptions.SCHEMA)
                        .map(ReadonlyConfig::fromMap)
                        .map(ReadonlyConfig::toConfig)
                        .orElse(null);

        ConnectionString connectionString = parseConnectionString(uri);
        if (connectionString.getCredential() == null) {
            throw new IllegalArgumentException(
                    "AmazonDocumentDB option 'uri' must include authentication credentials");
        }
        if (hasRetryWritesEnabled(uri)) {
            throw new IllegalArgumentException(
                    "AmazonDocumentDB does not support retryable writes; remove 'retryWrites=true' from option 'uri' or set it to false");
        }
        if (tls) {
            validateTlsCaFile(tlsCaFile);
        }
        validateBsonDocument(matchQuery, "match.query");
        if (projection != null) {
            validateBsonDocument(projection, "match.projection");
        }
    }

    /**
     * Builds driver settings with DocumentDB-safe overrides.
     *

View on GitHub (pinned to cf67b549a7)

Solutions

1. Embed credentials in the URI: mongodb://<user>:<password>@<cluster-endpoint>:27017 and URL-encode special characters in the password
2. Fetch the credential from AWS Secrets Manager / env substitution and template it into the uri at deploy time
3. Percent-encode characters like @ : / ? # in the password (e.g. @ -> %40) — an unencoded separator can make the parser treat the URI as credential-less
4. Verify env/variable interpolation actually resolved so credentials aren't dropped

Example fix

// before
uri = "mongodb://my-docdb-cluster.docdb.amazonaws.com:27017/?tls=true&tlsCAFile=rds-ca.crt"
// after
uri = "mongodb://admin:myP%40ssw0rd@my-docdb-cluster.docdb.amazonaws.com:27017/?tls=true&tlsCAFile=rds-ca.crt"

// pre-check the uri before submitting the job
function hasMongoCredentials(uri) {
  try {
    const u = new URL(uri.replace(/^mongodb(\+srv)?:\/\//, 'https://'));
    return Boolean(u.username && u.password);
  } catch (e) { return false; }
}
if (!hasMongoCredentials(process.env.DOCDB_URI)) {
  throw new Error("DOCDB_URI must include username:password, e.g. mongodb://user:pass@host:27017");
}

boolean hasCredentials(String uri) {
  int schemeEnd = uri.indexOf("://");
  if (schemeEnd < 0) return false;
  int at = uri.indexOf('@');
  if (at < 0) return false;
  String authority = uri.substring(schemeEnd + 3, at); // user:pass
  int colon = authority.indexOf(':');
  return colon > 0 && colon < authority.length() - 1;
}

try {
    AmazonDocumentDBConfig config = new AmazonDocumentDBConfig(readonlyConfig);
} catch (IllegalArgumentException e) {
    if (String.valueOf(e.getMessage()).contains("must include authentication credentials")) {
        throw new IllegalArgumentException("Fix the 'uri' option: embed mongodb://<user>:<url-encoded-password>@<host>:27017", e);
    }
    throw e;
}

When it happens

Trigger: Constructing AmazonDocumentDBConfig (any DocumentDB source/sink job start) where option 'uri' lacks a user/password component, e.g. 'mongodb://docdb.cluster-xxx.us-east-1.docdb.amazonaws.com:27017' with no credentials, so getCredential() returns null.

Common situations: Users pasting a plain DocumentDB cluster endpoint without credentials; credentials supplied via separate options or environment instead of the URI; copying URI examples that omit creds; config interpolation leaving ${VAR} empty so credentials silently vanish.

Understand the failure class

• Authentication and authorization failures — expired tokens, bad credentials, and missing scopes.

Related errors

• AmazonDocumentDB does not support retryable writes; remove '
• Invalid AmazonDocumentDB connection URI in option 'uri'
• The SQL config must contain at least one source table
• The SQL config must contain `INSERT INTO ... SELECT ...` syn
• Table name duplicate: %s

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