apache/seatunnel · error · IllegalStateException

Failed to open AzureCosmosDB source reader for database [%s]

Error message

Failed to open AzureCosmosDB source reader for database [%s], container [%s]

What it means

AzureCosmosDBSourceReader.open() builds the CosmosAsyncClient and fetches the target database/container handle. Any failure during client creation or the database/container lookup is wrapped into an IllegalStateException naming the database and container, with the underlying cause attached.

Source

Thrown at seatunnel-connectors-v2/connector-azurecosmosdb/src/main/java/org/apache/seatunnel/connectors/seatunnel/azurecosmosdb/source/AzureCosmosDBSourceReader.java:81

        this.context = context;
        this.config = config;
        this.deserializer = new CosmosItemDeserializer(rowType);
    }

    @Override
    public void open() {
        try {
            this.client =
                    new CosmosClientBuilder()
                            .endpoint(config.getResolvedEndpoint())
                            .key(config.getResolvedKey())
                            .endpointDiscoveryEnabled(false)
                            .gatewayMode()
                            .buildClient();
            this.container =
                    client.getDatabase(config.getDatabase()).getContainer(config.getContainer());
        } catch (Exception e) {
            throw new IllegalStateException(
                    String.format(
                            "Failed to open AzureCosmosDB source reader for database [%s], container [%s]",
                            config.getDatabase(), config.getContainer()),
                    e);
        }
    }

    @Override
    public void close() {
        if (client != null) {
            client.close();
        }
    }

    @Override
    public void pollNext(Collector<SeaTunnelRow> output) {
        AzureCosmosDBSourceSplit activeSplit;
        String continuationToken;

View on GitHub (pinned to cf67b549a7)

Solutions

1. Check the wrapped cause (`e`) for the real SDK error (401 auth, 404 NotFound, DNS/connect timeout)
2. Verify database and container names match those in the Azure portal (case-sensitive)
3. Confirm `uri` points to the correct account endpoint and `key` is that account's key
4. Test network reachability to `<account>.documents.azure.com:443` from worker nodes and check firewall rules

Example fix

// before (config names don't match Azure)
uri = "https://myaccount.documents.azure.com:443/"
database = "Shop"   // actual DB is "shop"
// after
uri = "https://myaccount.documents.azure.com:443/"
database = "shop"
container = "orders"

// before opening: verify names exist via a lightweight client call
client.getDatabase(dbName).read()
    .doOnSuccess(db -> System.out.println("DB ok: " + db.getId()))
    .block();

try {
    reader.open();
} catch (IllegalStateException e) {
    log.error("Cosmos open failed for db/container; cause={}", e.getCause(), e);
    // check auth (401) vs not-found (404) vs network before retrying
}

When it happens

Trigger: Calling open() when the SDK client cannot be built (bad endpoint/key, network unreachable) or `client.getDatabase(db).getContainer(container)` fails because the account is unreachable, credentials are wrong, or the database/container does not exist.

Common situations: Typo in database or container name; key/uri mismatched for the account; no network egress from the cluster to *.documents.azure.com; firewall/VNet rules blocking the worker; container deleted between planning and read.

Understand the failure class

Background: 'Could not be found', 'does not exist', 'not found in database': the resource-not-found family when an ID, slug, key, or URI lookup comes back empty — this error's family across 20 libraries.

Related errors

• Failed to read AzureCosmosDB data from database [%s], contai
• Failed to fetch metadata from Gravitino for metadata: %s
• fail get tableSchema:
• DataTypeChanger not reset
• CREATE_ACTIVEMQ_CLIENT_FAILED

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