apache/seatunnel · error · BigtableConnectorException

WRITE_FAILED

WRITE_FAILED

Error message

Failed to mutate row in table 

What it means

BigtableClient.mutateRow wraps any exception from dataClient.mutateRow into BigtableConnectorException with WRITE_FAILED. A single-row write (RowMutation) failed at the Bigtable service or client level.

Source

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

                    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) {
            throw new BigtableConnectorException(
                    BigtableConnectorErrorCode.WRITE_FAILED,
                    "Failed to mutate row in table " + parameters.getTable(),
                    e);
        }
    }

    /**
     * Applies a batch of row mutations to Bigtable using BulkMutation for efficiency.
     *
     * @param mutations list of (rowKey, Mutation) pairs to apply
     */
    public void bulkMutate(List<RowKeyMutation> mutations) {
        if (mutations.isEmpty()) {
            return;
        }
        try {
            BulkMutation bulk = BulkMutation.create(parameters.getTable());
            for (RowKeyMutation entry : mutations) {

View on GitHub (pinned to cf67b549a7)

Solutions

1. Confirm the target column family exists in the Bigtable table and matches the sink mapping
2. Check IAM permissions (Bigtable User role) for the service account
3. Inspect the cause exception; retry on transient errors (DEADLINE_EXCEEDED, UNAVAILABLE) with backoff
4. Validate row sizes and cell counts against Bigtable limits

// ensure column families exist before writing
for (String cf : requiredColumnFamilies) {
  assert existingFamilies.contains(cf) : "Missing column family: " + cf;
}

try {
  client.mutateRow(rowMutation);
} catch (BigtableConnectorException e) {
  if (isTransient(e.getCause())) retryWithBackoff(rowMutation);
  else throw e;
}

When it happens

Trigger: mutateRow(RowMutation) is called and the underlying RPC fails: nonexistent column family, row key or cell size limits exceeded, deadline/timeout, permission denied on the table, or transient server error.

Common situations: Writing to a column family that was never created; rows larger than Bigtable limits (256MB); IAM role lacking bigtable.tables.mutateRows; network blips or throttling on busy instances.

Related errors

• TABLE_QUERY_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/c989ff11496d7f44. Report an issue: GitHub.