{"record":{"id":"7369f83278e9aba2","repo":"apache/seatunnel","slug":"samplerowkeys-failed-for-table-fallback-to-s","errorCode":null,"errorMessage":"sampleRowKeys failed for table [{}], fallback to single split","messagePattern":"sampleRowKeys failed for table \\[(.+?)\\], fallback to single split","errorType":"console","errorClass":null,"httpStatus":null,"severity":"warning","filePath":"seatunnel-connectors-v2/connector-google-bigtable/src/main/java/org/apache/seatunnel/connectors/seatunnel/bigtable/source/BigtableSourceSplitEnumerator.java","lineNumber":270,"sourceCode":"\n        List<KeyOffset> samples;\n        try {\n            samples = getBigtableClient().sampleRowKeys();\n        } catch (EnumeratorClosedException e) {\n            // close() raced discovery — not a Bigtable API failure; do not log as sampleRowKeys\n            // failed and do not fabricate a whole-range fallback split.\n            log.info(\n                    \"Enumerator closed during split discovery for table [{}]; skipping discovery\",\n                    parameters.getTable());\n            return Collections.emptySet();\n        } catch (Exception e) {\n            if (isClosed()) {\n                log.info(\n                        \"Enumerator closed during split discovery for table [{}]; skipping discovery\",\n                        parameters.getTable());\n                return Collections.emptySet();\n            }\n            log.warn(\n                    \"sampleRowKeys failed for table [{}], fallback to single split\",\n                    parameters.getTable(),\n                    e);\n            return Collections.singleton(new BigtableSourceSplit(0, userStart, userEnd));\n        }\n\n        if (isClosed()) {\n            return Collections.emptySet();\n        }\n\n        if (samples == null || samples.isEmpty()) {\n            return Collections.singleton(new BigtableSourceSplit(0, userStart, userEnd));\n        }\n\n        Set<BigtableSourceSplit> splits = new LinkedHashSet<>();\n        String rangeStart = \"\";\n        int index = 0;\n        for (KeyOffset sample : samples) {","sourceCodeStart":252,"sourceCodeEnd":288,"githubUrl":"https://github.com/apache/seatunnel/blob/cf67b549a7a6c35fa0beb12d83c62892427ea919/seatunnel-connectors-v2/connector-google-bigtable/src/main/java/org/apache/seatunnel/connectors/seatunnel/bigtable/source/BigtableSourceSplitEnumerator.java#L252-L288","documentation":"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.","triggerScenarios":"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.","commonSituations":"VPC without egress to bigtable.googleapis.com, workload identity/credentials misconfigured, typos in project/instance/table IDs, transient gRPC UNAVAILABLE during cluster resize.","solutions":["Check network connectivity and firewall/proxy rules so the job can reach bigtable.googleapis.com","Verify Google Cloud credentials (service account key, workload identity) are valid and have bigtable.tables.read access","Confirm project/instance/table names in the source options are correct and the table exists","If the warning persists, accept single-split execution or increase client timeouts/retry settings"],"exampleFix":"// before\n\"table_name\" = \"my-table\" // instance typo causing sampleRowKeys failure\n// after\n{\n  \"project_id\" = \"my-project\",\n  \"instance_name\" = \"my-instance\",\n  \"table_name\" = \"my-table\"\n}","handlingStrategy":"fallback","validationCode":"// Before the job: verify table and connectivity\ntry (var admin = BigtableDataClientFactory/... ) {\n  // or simply:\n  // gcloud bigtable instances tables describe $TABLE --instance=$INSTANCE\n  tableAdminClient.getTable(\"my-table\");\n  tableAdminClient.sampleRowKeys(\"my-table\");\n}","typeGuard":null,"tryCatchPattern":"try {\n  keys = tableAdminClient.sampleRowKeys(tableId);\n} catch (ApiException e) {\n  log.warn(\"sampleRowKeys failed, single split\", e);\n  splits = List.of(new BigtableSourceSplit(0, start, end));\n}","preventionTips":["Pre-flight check sampleRowKeys/gcloud access from the job environment","Validate credentials with a lightweight storage/iam API call before submitting","Confirm project/instance/table IDs against gcloud config","Monitor logs for the fallback warning; it signals reduced read parallelism"],"tags":["bigtable","fallback","grpc","parallelism"],"backgroundTag":"network-request-failed","analyzedSha":"cf67b549a7a6c35fa0beb12d83c62892427ea919","analyzedAt":"2026-09-10T21:44:55.265Z","contentChangedAt":"2026-09-10T21:44:55.265Z","schemaVersion":2},"datasetVersion":"2026-09-23T08:17:48.524Z"}