apache/seatunnel · error · IllegalArgumentException

AzureCosmosDB requires key, primary_key, secondary_key, or a

Error message

AzureCosmosDB requires key, primary_key, secondary_key, or a connection string to resolve the key

What it means

AzureCosmosDBConfig validates that an authentication key can be resolved for the Cosmos DB account. The key comes from `key`, `primaryKey`, `secondaryKey`, or is parsed out of `connectionString`; if none is available it throws IllegalArgumentException at config construction.

Source

Thrown at seatunnel-connectors-v2/connector-azurecosmosdb/src/main/java/org/apache/seatunnel/connectors/seatunnel/azurecosmosdb/config/AzureCosmosDBConfig.java:72

        this.secondaryConnectionString =
                config.getOptional(AzureCosmosDBSourceOptions.SECONDARY_CONNECTION_STRING)
                        .orElse(null);
        this.database = config.get(AzureCosmosDBSourceOptions.DATABASE);
        this.container = config.get(AzureCosmosDBSourceOptions.CONTAINER);
        this.query = config.get(AzureCosmosDBSourceOptions.QUERY);
        this.maxItemCount = config.get(AzureCosmosDBSourceOptions.MAX_ITEM_COUNT);
        this.schema =
                config.getOptional(ConnectorCommonOptions.SCHEMA)
                        .map(ReadonlyConfig::fromMap)
                        .map(ReadonlyConfig::toConfig)
                        .orElse(null);

        if (getResolvedEndpoint() == null) {
            throw new IllegalArgumentException(
                    "AzureCosmosDB requires uri, endpoint, or connection string to resolve the endpoint");
        }
        if (getResolvedKey() == null) {
            throw new IllegalArgumentException(
                    "AzureCosmosDB requires key, primary_key, secondary_key, or a connection string to resolve the key");
        }
    }

    public String getResolvedEndpoint() {
        String resolvedEndpoint = firstNonBlank(uri, endpoint);
        if (resolvedEndpoint != null) {
            return resolvedEndpoint;
        }

        return firstNonBlank(
                parseConnectionString(primaryConnectionString).get("endpoint"),
                parseConnectionString(secondaryConnectionString).get("endpoint"));
    }

    public String getResolvedKey() {
        String resolvedKey = firstNonBlank(key, primaryKey, secondaryKey);
        if (resolvedKey != null) {

View on GitHub (pinned to cf67b549a7)

Solutions

Set `key = "<account primary or secondary key>"` in the config
Or provide `primary_key` / `secondary_key` explicitly
Or provide a full `connectionString` so endpoint and key are both derived
Verify the secret is actually injected (env var, vault placeholder) and non-blank

Example fix

// before
sink {
  AzureCosmosDB {
    uri = "https://myaccount.documents.azure.com:443/"
    database = "shop"
  }
}
// after
sink {
  AzureCosmosDB {
    uri = "https://myaccount.documents.azure.com:443/"
    key = "${COSMOS_KEY}"
    database = "shop"
  }
}

Defensive patterns

Strategy: validation

Validate before calling

boolean hasKey = cfg.getOptional(AzureCosmosDBConfig.KEY).isPresent()
    || cfg.getOptional(AzureCosmosDBConfig.PRIMARY_KEY).isPresent()
    || cfg.getOptional(AzureCosmosDBConfig.SECONDARY_KEY).isPresent()
    || cfg.getOptional(AzureCosmosDBConfig.CONNECTION_STRING).isPresent();
if (!hasKey) throw new IllegalArgumentException("Provide key, primary_key, secondary_key, or connectionString");

Prevention

Store the key in an env var or secret store and reference it, never hardcode
Remember connectionString alone satisfies both endpoint and key requirements
Check secret injection (K8s secrets, CI placeholders) resolves to a non-blank value

When it happens

Trigger: Building the connector config when none of `key`, `primary_key`, `secondary_key`, nor `connectionString` resolve to a non-blank value, even though an endpoint was resolved successfully.

Common situations: User set the uri but forgot the key; key stored only in an env var that was not set; using a connection string format the parser does not recognize; secret placeholder not substituted in a CI/K8s deployment.

Related errors

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