{"record":{"id":"f031bf239f3928e4","repo":"apache/seatunnel","slug":"failed-to-read-azurecosmosdb-data-from-database","errorCode":null,"errorMessage":"Failed to read AzureCosmosDB data from database [%s], container [%s] with query [%s]","messagePattern":"Failed to read AzureCosmosDB data from database \\[(.+?)\\], container \\[(.+?)\\] with query \\[(.+?)\\]","errorType":"exception","errorClass":"IllegalStateException","httpStatus":null,"severity":"error","filePath":"seatunnel-connectors-v2/connector-azurecosmosdb/src/main/java/org/apache/seatunnel/connectors/seatunnel/azurecosmosdb/source/AzureCosmosDBSourceReader.java","lineNumber":211,"sourceCode":"\n        try {\n            Iterator<FeedResponse<Object>> pageIterator;\n            if (isLastPage(continuationToken)) {\n                pageIterator =\n                        container\n                                .<Object>queryItems(config.getQuery(), queryOptions, Object.class)\n                                .iterableByPage(config.getMaxItemCount())\n                                .iterator();\n            } else {\n                pageIterator =\n                        container\n                                .<Object>queryItems(config.getQuery(), queryOptions, Object.class)\n                                .iterableByPage(continuationToken, config.getMaxItemCount())\n                                .iterator();\n            }\n            return pageIterator.hasNext() ? pageIterator.next() : null;\n        } catch (Exception e) {\n            throw new IllegalStateException(\n                    String.format(\n                            \"Failed to read AzureCosmosDB data from database [%s], container [%s] with query [%s]\",\n                            config.getDatabase(), config.getContainer(), config.getQuery()),\n                    e);\n        }\n    }\n\n    private static boolean isLastPage(String continuationToken) {\n        return continuationToken == null || continuationToken.isEmpty();\n    }\n\n    private void finishReader() {\n        context.signalNoMoreElement();\n        finished = true;\n    }\n\n    private void finishReaderIfNoMoreWork() {\n        if (currentSplit == null && pendingSplits.isEmpty() && noMoreSplit) {","sourceCodeStart":193,"sourceCodeEnd":229,"githubUrl":"https://github.com/apache/seatunnel/blob/cf67b549a7a6c35fa0beb12d83c62892427ea919/seatunnel-connectors-v2/connector-azurecosmosdb/src/main/java/org/apache/seatunnel/connectors/seatunnel/azurecosmosdb/source/AzureCosmosDBSourceReader.java#L193-L229","documentation":"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.","triggerScenarios":"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).","commonSituations":"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.","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)"],"exampleFix":"// before\nquery = \"SELECT * FROM orders WHERE o.status = 'OPEN'\" // wrong alias/property\n// after\nquery = \"SELECT * FROM c WHERE c.status = 'OPEN'\"","handlingStrategy":"retry","validationCode":"// validate query syntax in Azure portal Data Explorer before putting it in the config\n// ensure fields referenced exist, e.g. SELECT VALUE c FROM c WHERE IS_DEFINED(c.status)","typeGuard":null,"tryCatchPattern":"try {\n    Page<CosmosItemProperties> page = fetchPage(token);\n} catch (IllegalStateException e) {\n    if (isThrottled(e.getCause())) { backoffAndRetry(token); } // 429\n    else { log.error(\"Query failed: {}\", e.getCause()); throw e; }\n}","preventionTips":["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"],"tags":["azure-cosmosdb","query","throttling","network"],"backgroundTag":"database-query-failed","analyzedSha":"cf67b549a7a6c35fa0beb12d83c62892427ea919","analyzedAt":"2026-09-10T21:44:55.265Z","contentChangedAt":"2026-09-10T21:44:55.265Z","schemaVersion":2},"datasetVersion":"2026-09-14T05:17:10.506Z"}