apache/seatunnel · critical · BigtableConnectorException

CONNECTION_FAILED

CONNECTION_FAILED

Error message

Failed to create Bigtable client for project=

What it means

BigtableClient.createInstance wraps IOException from BigtableDataClient.create(settings) in a BigtableConnectorException with CONNECTION_FAILED. It means the Google Cloud Bigtable data client could not be constructed — usually credential, network, or invalid project/instance settings.

Source

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

            BigtableDataSettings.Builder settingsBuilder =
                    BigtableDataSettings.newBuilder()
                            .setProjectId(parameters.getProjectId())
                            .setInstanceId(parameters.getInstanceId());

            if (parameters.getCredentialsPath() != null
                    && !parameters.getCredentialsPath().isEmpty()) {
                try (FileInputStream credStream =
                        new FileInputStream(parameters.getCredentialsPath())) {
                    GoogleCredentials credentials =
                            ServiceAccountCredentials.fromStream(credStream);
                    settingsBuilder.stubSettings().setCredentialsProvider(() -> credentials);
                }
            }

            BigtableDataClient client = BigtableDataClient.create(settingsBuilder.build());
            return new BigtableClient(client, parameters);
        } catch (IOException e) {
            throw new BigtableConnectorException(
                    BigtableConnectorErrorCode.CONNECTION_FAILED,
                    "Failed to create Bigtable client for project="
                            + parameters.getProjectId()
                            + ", instance="
                            + parameters.getInstanceId(),
                    e);
        }
    }

    /**
     * Applies a single row mutation to Bigtable.
     *
     * @param rowMutation the row mutation to apply
     */
    public void mutateRow(RowMutation rowMutation) {
        try {
            dataClient.mutateRow(rowMutation);
        } catch (Exception e) {

View on GitHub (pinned to cf67b549a7)

Solutions

1. Verify project-id and instance-id values in the connector config match your GCP Bigtable instance
2. Ensure credentials are available: set GOOGLE_APPLICATION_CREDENTIALS to a valid service-account JSON or run inside GCP with a proper service account
3. Test network reachability to bigtable.googleapis.com:443 (proxy/firewall rules)
4. Check the wrapped IOException (getCause) for the precise root cause

Example fix

// before
BigtableSink {
  project-id = "my-projcet"
  instance-id = "my-inst"
}
// after
BigtableSink {
  project-id = "my-project"
  instance-id = "my-instance"
}
export GOOGLE_APPLICATION_CREDENTIALS=/path/to/sa.json

assert projectId != null && !projectId.isBlank();
assert instanceId != null && !instanceId.isBlank();
assert System.getenv("GOOGLE_APPLICATION_CREDENTIALS") != null || isRunningOnGcp();

try {
  BigtableClient client = BigtableClient.createInstance(parameters);
} catch (BigtableConnectorException e) {
  if (e.getErrorCode() == BigtableConnectorErrorCode.CONNECTION_FAILED) {
    // check projectId/instanceId, credentials, network; retry with backoff
  }
}

When it happens

Trigger: createInstance() calls BigtableDataClient.create(settingsBuilder.build()) which fails with IOException: unreachable endpoint, bad project/instance id, or unresolvable credentials (e.g. GOOGLE_APPLICATION_CREDENTIALS missing/invalid).

Common situations: Wrong projectId or instanceId in connector config; no network/firewall access to bigtable.googleapis.com; missing service account key file; running outside GCP without credentials configured.

Understand the failure class

Background: ECONNREFUSED and "connection refused" / "could not connect to server" errors: what they mean and how to fix them — this error's family across 44 libraries.

Related errors

• Failed to open BigQueryCatalog
• CLIENT_CREATE_FAILED
• WRITE_FAILED
• TABLE_QUERY_FAILED
• CONNECTION_FAILED

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