apache/seatunnel · error · IllegalStateException

Failed to read AzureCosmosDB data from database [%s], contai

Error message

Failed to read AzureCosmosDB data from database [%s], container [%s] with query [%s]

What it means

AzureCosmosDBSourceReader.fetchPage() runs the configured `query` via queryItems and pulls one page of results using the continuation token. Any exception from the SDK during the query or page iteration is wrapped into an IllegalStateException identifying database, container, and query, with the original exception as cause.

Source

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

        try {
            Iterator<FeedResponse<Object>> pageIterator;
            if (isLastPage(continuationToken)) {
                pageIterator =
                        container
                                .<Object>queryItems(config.getQuery(), queryOptions, Object.class)
                                .iterableByPage(config.getMaxItemCount())
                                .iterator();
            } else {
                pageIterator =
                        container
                                .<Object>queryItems(config.getQuery(), queryOptions, Object.class)
                                .iterableByPage(continuationToken, config.getMaxItemCount())
                                .iterator();
            }
            return pageIterator.hasNext() ? pageIterator.next() : null;
        } catch (Exception e) {
            throw new IllegalStateException(
                    String.format(
                            "Failed to read AzureCosmosDB data from database [%s], container [%s] with query [%s]",
                            config.getDatabase(), config.getContainer(), config.getQuery()),
                    e);
        }
    }

    private static boolean isLastPage(String continuationToken) {
        return continuationToken == null || continuationToken.isEmpty();
    }

    private void finishReader() {
        context.signalNoMoreElement();
        finished = true;
    }

    private void finishReaderIfNoMoreWork() {
        if (currentSplit == null && pendingSplits.isEmpty() && noMoreSplit) {

View on GitHub (pinned to cf67b549a7)

Solutions

Inspect the wrapped cause for the SDK status code (400 bad query, 429 throttle, 401 auth)
Validate the `query` SQL against the container in the Azure Data Explorer portal first
Lower `maxItemCount` page size to reduce RU and memory pressure; retry on 429 with backoff
Re-run the job if the failure was transient (continuation tokens allow resuming)

Example fix

// before
query = "SELECT * FROM orders WHERE o.status = 'OPEN'" // wrong alias/property
// after
query = "SELECT * FROM c WHERE c.status = 'OPEN'"

Defensive patterns

Strategy: retry

Validate before calling

// validate query syntax in Azure portal Data Explorer before putting it in the config
// ensure fields referenced exist, e.g. SELECT VALUE c FROM c WHERE IS_DEFINED(c.status)

Try / catch

try {
    Page<CosmosItemProperties> page = fetchPage(token);
} catch (IllegalStateException e) {
    if (isThrottled(e.getCause())) { backoffAndRetry(token); } // 429
    else { log.error("Query failed: {}", e.getCause()); throw e; }
}

Prevention

Test the exact query string in the portal's Data Explorer first
Lower `maxItemCount` to reduce RU consumption and 429 throttling
Prefer `SELECT * FROM c` style queries with proper `c` aliases

When it happens

Trigger: Calling fetchPage() when the Cosmos SQL query is syntactically invalid, references missing fields/containers, or the SDK call fails mid-read (network drop, 429 throttling, expired/revoked key, continuation token no longer valid).

Common situations: Malformed Cosmos SQL in the `query` option; querying a property that doesn't exist; partition hitting request-unit (RU) throttling (429); transient network failure during long reads; very large pages exceeding memory.

Understand the failure class

Background: Database query failed: Internal Server Error 500s wrapping SQL, Prisma, and connection failures — what to check first — this error's family across 16 libraries.

Related errors

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