apache/seatunnel · error · BigtableConnectorException

TABLE_QUERY_FAILED

TABLE_QUERY_FAILED

Error message

Failed to sample row keys for table 

What it means

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.

Source

Thrown at seatunnel-connectors-v2/connector-google-bigtable/src/main/java/org/apache/seatunnel/connectors/seatunnel/bigtable/client/BigtableClient.java:158

    public BigtableDataClient getDataClient() {
        return dataClient;
    }

    /**
     * Samples approximate tablet-boundary row keys used by the enumerator to build parallel source
     * splits.
     *
     * <p>The returned keys delimit roughly equal-size ranges; the last key is typically empty,
     * meaning the table end.
     *
     * @return sampled tablet-boundary keys
     * @throws BigtableConnectorException if the RPC fails
     */
    public List<KeyOffset> sampleRowKeys() {
        try {
            return dataClient.sampleRowKeys(parameters.getTable());
        } catch (Exception e) {
            throw new BigtableConnectorException(
                    BigtableConnectorErrorCode.TABLE_QUERY_FAILED,
                    "Failed to sample row keys for table " + parameters.getTable(),
                    e);
        }
    }

    @Override
    public void close() {
        if (dataClient != null) {
            try {
                dataClient.close();
                dataClient = null;
            } catch (Exception e) {
                log.error("Failed to close Bigtable data client", e);
            }
        }
    }

View on GitHub (pinned to cf67b549a7)

Solutions

1. Verify the table name/id in config matches an existing Bigtable table
2. Grant the service account read access (Bigtable Reader role or higher)
3. Check network connectivity and endpoint configuration; retry transient failures
4. Inspect the cause exception for NOT_FOUND vs PERMISSION_DENIED vs UNAVAILABLE

boolean tableExists = adminClient.exists(TableId.of(projectId, instanceId, tableId));
if (!tableExists) throw new IllegalStateException("Bigtable table missing: " + tableId);

try {
  List<KeyOffset> offsets = client.sampleRowKeys();
} catch (BigtableConnectorException e) {
  // fall back to single-split read, as connector tests do
  offsets = Collections.singletonList(fullTableRange);
}

When it happens

Trigger: 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.

Common situations: 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).

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

• WRITE_FAILED
• CONNECTION_FAILED
• Failed to open BigQueryCatalog
• Failed to list BigQuery databases (datasets)
• Failed to list tables in dataset:

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