apache/seatunnel · error · IllegalArgumentException

AzureCosmosDB requires uri, endpoint, or connection string t

Error message

AzureCosmosDB requires uri, endpoint, or connection string to resolve the endpoint

What it means

AzureCosmosDBConfig validates at construction time that the connector can determine which Cosmos DB account endpoint to talk to. It resolves the endpoint from the `uri` or `endpoint` options, falling back to parsing a `connectionString`; if all are absent, it throws IllegalArgumentException before any network call is made.

Source

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

                config.getOptional(AzureCosmosDBSourceOptions.SECONDARY_KEY).orElse(null);
        this.primaryConnectionString =
                config.getOptional(AzureCosmosDBSourceOptions.PRIMARY_CONNECTION_STRING)
                        .orElse(null);
        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"));
    }

View on GitHub (pinned to cf67b549a7)

Solutions

1. Add `uri = "https://<account>.documents.azure.com:443/"` to the CosmosDB source/sink config
2. Or set `endpoint` with the account endpoint URL
3. Or set `connectionString` (AccountEndpoint/AccountKey format) and let the connector parse both endpoint and key
4. Verify the HOCON/env config actually passes the option through (check ReadonlyConfig keys, typos, and placeholder substitution)

Example fix

// before
source {
  AzureCosmosDB {
    database = "shop"
    container = "orders"
  }
}
// after
source {
  AzureCosmosDB {
    uri = "https://myaccount.documents.azure.com:443/"
    key = "<account-key>"
    database = "shop"
    container = "orders"
  }
}

boolean hasEndpoint = cfg.getOptional(AzureCosmosDBConfig.URI).isPresent()
    || cfg.getOptional(AzureCosmosDBConfig.ENDPOINT).isPresent()
    || cfg.getOptional(AzureCosmosDBConfig.CONNECTION_STRING).isPresent();
if (!hasEndpoint) throw new IllegalArgumentException("Set uri, endpoint, or connectionString for AzureCosmosDB");

When it happens

Trigger: Creating the connector config (e.g. via AzureCosmosDBSource/Sink factory or ReadonlyConfig conversion) when neither `uri`, `endpoint`, nor `connectionString` is set in the job config.

Common situations: User forgot the uri/endpoint option entirely; option name typo (e.g. `url` instead of `uri`); config loaded from an HOCON map missing the cosmos section; a placeholder value left empty after templating.

Understand the failure class

Background: "is required", "must be set", "missing required field": configuration validation errors across open-source libraries — this error's family across 36 libraries.

Related errors

• Please configure `table_name`, not allow null table name in
• Schema config can not be empty
• Schema config need option [schema], please correct your conf
• Unknown format type:
• Option '${option}' cannot be blank

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