apache/seatunnel · warning

sampleRowKeys failed for table

Error message

sampleRowKeys failed for table [{}], fallback to single split

What it means

During split enumeration the Bigtable connector calls sampleRowKeys to divide the table's row space into parallel splits. If that RPC fails (e.g. connectivity, auth, or API error), the enumerator logs this warning and falls back to a single split covering the user-provided start/end rows, so the job still runs but with reduced parallelism.

Solutions

1. Check network connectivity and firewall/proxy rules so the job can reach bigtable.googleapis.com
2. Verify Google Cloud credentials (service account key, workload identity) are valid and have bigtable.tables.read access
3. Confirm project/instance/table names in the source options are correct and the table exists
4. If the warning persists, accept single-split execution or increase client timeouts/retry settings

Example fix

// before
"table_name" = "my-table" // instance typo causing sampleRowKeys failure
// after
{
  "project_id" = "my-project",
  "instance_name" = "my-instance",
  "table_name" = "my-table"
}

// Before the job: verify table and connectivity
try (var admin = BigtableDataClientFactory/... ) {
  // or simply:
  // gcloud bigtable instances tables describe $TABLE --instance=$INSTANCE
  tableAdminClient.getTable("my-table");
  tableAdminClient.sampleRowKeys("my-table");
}

try {
  keys = tableAdminClient.sampleRowKeys(tableId);
} catch (ApiException e) {
  log.warn("sampleRowKeys failed, single split", e);
  splits = List.of(new BigtableSourceSplit(0, start, end));
}

When it happens

Trigger: buildSplits() invokes Bigtable's sampleRowKeys and catches an exception from the admin/data client: network unreachable to Bigtable endpoint, invalid service account credentials, table does not exist yet, or a transient gRPC error.

Common situations: VPC without egress to bigtable.googleapis.com, workload identity/credentials misconfigured, typos in project/instance/table IDs, transient gRPC UNAVAILABLE during cluster resize.

Related errors

• Shallow key discovery failed on path
• Batch write failed ( element(s)); falling back to…
• BigtableSourceSplitEnumerator already closed; cannot create…
• BigtableSourceSplitEnumerator closed during client creation
• can't load jar use current thread classloader, use…

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

Appendix: source

Thrown at seatunnel-connectors-v2/connector-google-bigtable/src/main/java/org/apache/seatunnel/connectors/seatunnel/bigtable/source/BigtableSourceSplitEnumerator.java:270

        List<KeyOffset> samples;
        try {
            samples = getBigtableClient().sampleRowKeys();
        } catch (EnumeratorClosedException e) {
            // close() raced discovery — not a Bigtable API failure; do not log as sampleRowKeys
            // failed and do not fabricate a whole-range fallback split.
            log.info(
                    "Enumerator closed during split discovery for table [{}]; skipping discovery",
                    parameters.getTable());
            return Collections.emptySet();
        } catch (Exception e) {
            if (isClosed()) {
                log.info(
                        "Enumerator closed during split discovery for table [{}]; skipping discovery",
                        parameters.getTable());
                return Collections.emptySet();
            }
            log.warn(
                    "sampleRowKeys failed for table [{}], fallback to single split",
                    parameters.getTable(),
                    e);
            return Collections.singleton(new BigtableSourceSplit(0, userStart, userEnd));
        }

        if (isClosed()) {
            return Collections.emptySet();
        }

        if (samples == null || samples.isEmpty()) {
            return Collections.singleton(new BigtableSourceSplit(0, userStart, userEnd));
        }

        Set<BigtableSourceSplit> splits = new LinkedHashSet<>();
        String rangeStart = "";
        int index = 0;
        for (KeyOffset sample : samples) {

View on GitHub (pinned to cf67b549a7)