{"record":{"id":"c954aa56eb0266be","repo":"apache/seatunnel","slug":"table-query-failed","errorCode":"TABLE_QUERY_FAILED","errorMessage":"Failed to sample row keys for table ","messagePattern":"Failed to sample row keys for table ","errorType":"error_code","errorClass":"BigtableConnectorException","httpStatus":null,"severity":"error","filePath":"seatunnel-connectors-v2/connector-google-bigtable/src/main/java/org/apache/seatunnel/connectors/seatunnel/bigtable/client/BigtableClient.java","lineNumber":158,"sourceCode":"    public BigtableDataClient getDataClient() {\n        return dataClient;\n    }\n\n    /**\n     * Samples approximate tablet-boundary row keys used by the enumerator to build parallel source\n     * splits.\n     *\n     * <p>The returned keys delimit roughly equal-size ranges; the last key is typically empty,\n     * meaning the table end.\n     *\n     * @return sampled tablet-boundary keys\n     * @throws BigtableConnectorException if the RPC fails\n     */\n    public List<KeyOffset> sampleRowKeys() {\n        try {\n            return dataClient.sampleRowKeys(parameters.getTable());\n        } catch (Exception e) {\n            throw new BigtableConnectorException(\n                    BigtableConnectorErrorCode.TABLE_QUERY_FAILED,\n                    \"Failed to sample row keys for table \" + parameters.getTable(),\n                    e);\n        }\n    }\n\n    @Override\n    public void close() {\n        if (dataClient != null) {\n            try {\n                dataClient.close();\n                dataClient = null;\n            } catch (Exception e) {\n                log.error(\"Failed to close Bigtable data client\", e);\n            }\n        }\n    }\n","sourceCodeStart":140,"sourceCodeEnd":176,"githubUrl":"https://github.com/apache/seatunnel/blob/cf67b549a7a6c35fa0beb12d83c62892427ea919/seatunnel-connectors-v2/connector-google-bigtable/src/main/java/org/apache/seatunnel/connectors/seatunnel/bigtable/client/BigtableClient.java#L140-L176","documentation":"BigtableClient.sampleRowKeys wraps RPC failures from dataClient.sampleRowKeys into BigtableConnectorException with TABLE_QUERY_FAILED. Sample-row-keys is used to discover split boundaries for parallel reads, so this failure aborts split enumeration.","triggerScenarios":"sampleRowKeys() calls dataClient.sampleRowKeys(parameters.getTable()); the RPC fails due to table not existing, permission denied, network error, or invalid table id in the connector config.","commonSituations":"Typo in table name during source/split-enumerator setup; table dropped before job start; service account missing bigtable.tables.readRows permission; connectivity drop to the Bigtable endpoint (tests mock this failure to verify fallback behavior).","solutions":["Verify the table name/id in config matches an existing Bigtable table","Grant the service account read access (Bigtable Reader role or higher)","Check network connectivity and endpoint configuration; retry transient failures","Inspect the cause exception for NOT_FOUND vs PERMISSION_DENIED vs UNAVAILABLE"],"exampleFix":null,"handlingStrategy":"try-catch","validationCode":"boolean tableExists = adminClient.exists(TableId.of(projectId, instanceId, tableId));\nif (!tableExists) throw new IllegalStateException(\"Bigtable table missing: \" + tableId);","typeGuard":null,"tryCatchPattern":"try {\n  List<KeyOffset> offsets = client.sampleRowKeys();\n} catch (BigtableConnectorException e) {\n  // fall back to single-split read, as connector tests do\n  offsets = Collections.singletonList(fullTableRange);\n}","preventionTips":["Verify table name in config before job submission","Grant read permissions to the service account","Handle missing tables with explicit pre-checks","Implement sampleRowKeys fallback to single split"],"tags":["gcp","bigtable","split-enumeration","rpc"],"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"}