{"record":{"id":"770bbed4859183ec","repo":"apache/beam","slug":"could-not-apply-mutation-for-row-key-s-v","errorCode":null,"errorMessage":"could not apply mutation for row key='%s': %v","messagePattern":"could not apply mutation for row key='(.+?)': (.+?)","errorType":"exception","errorClass":null,"httpStatus":null,"severity":"error","filePath":"sdks/go/pkg/beam/io/bigtableio/bigtable.go","lineNumber":174,"sourceCode":"\tif err := f.client.Close(); err != nil {\n\t\treturn fmt.Errorf(\"could not close data operations client: %v\", err)\n\t}\n\treturn nil\n}\n\nfunc (f *writeFn) ProcessElement(ctx context.Context, key int, values func(*Mutation) bool) error {\n\n\tvar mutation Mutation\n\tfor values(&mutation) {\n\n\t\terr := validateMutation(mutation)\n\t\tif err != nil {\n\t\t\treturn fmt.Errorf(\"invalid bigtableio.Mutation: %s\", err)\n\t\t}\n\n\t\terr = f.table.Apply(ctx, mutation.RowKey, getBigtableMutation(mutation))\n\t\tif err != nil {\n\t\t\treturn fmt.Errorf(\"could not apply mutation for row key='%s': %v\", mutation.RowKey, err)\n\t\t}\n\n\t}\n\n\treturn nil\n}\n\ntype writeBatchFn struct {\n\t// Project is the project\n\tProject string `json:\"project\"`\n\t// InstanceID is the bigtable instanceID\n\tInstanceID string `json:\"instanceId\"`\n\t// Client is the bigtable.Client\n\tclient *bigtable.Client `json:\"-\"`\n\t// TableName is the qualified table identifier.\n\tTableName string `json:\"tableName\"`\n\t// Table is a bigtable.Table instance with an eventual open connection\n\ttable *bigtable.Table `json:\"-\"`","sourceCodeStart":156,"sourceCodeEnd":192,"githubUrl":"https://github.com/apache/beam/blob/12126d8942aaf848030c478b4c6a28c6af861c66/sdks/go/pkg/beam/io/bigtableio/bigtable.go#L156-L192","documentation":"In the streaming (DoFn) write path of bigtableio, ProcessElement calls table.Apply for each Mutation. If the Bigtable data client rejects the single-row mutation, the underlying Cloud Bigtable error is wrapped with the affected row key so the failing row can be identified. This indicates the write itself failed, not that the Mutation was structurally invalid.","triggerScenarios":"f.table.Apply(ctx, mutation.RowKey, ...) returns a non-nil error in bigtableio.writeFn.ProcessElement (bigtable.go:174) — e.g. server rejects the mutation, context cancelled/deadline exceeded, permission denied on the table, or row key invalid.","commonSituations":"IAM service account lacking Bigtable user role; row key containing invalid characters or exceeding size limits; mutation exceeding cell/column limits; transient gRPC errors or job cancellation mid-write; wrong project/instance so the table doesn't exist.","solutions":["Inspect the wrapped %v error for the root cause (grpc status code) and fix that condition first","Verify the service account has roles/bigtable.user on the instance and that Project/InstanceID/TableName are correct","Validate the row key (non-empty, valid UTF-8/bytes, within size limits) before writing","For large or flaky writes, prefer the batch path (writeBatchFn / ApplyBulk) and retry transient statuses with backoff"],"exampleFix":"// before\nerr = f.table.Apply(ctx, mutation.RowKey, getBigtableMutation(mutation))\nif err != nil {\n\treturn fmt.Errorf(\"could not apply mutation for row key='%s': %v\", mutation.RowKey, err)\n}\n// after: check row key and transient errors before failing\nif mutation.RowKey == \"\" {\n\treturn fmt.Errorf(\"bigtableio.Mutation has empty row key\")\n}\nif err := f.table.Apply(ctx, mutation.RowKey, getBigtableMutation(mutation)); err != nil {\n\tif ctx.Err() != nil {\n\t\treturn ctx.Err() // let the runner retry\n\t}\n\treturn fmt.Errorf(\"could not apply mutation for row key='%s': %v\", mutation.RowKey, err)\n}","handlingStrategy":"try-catch","validationCode":"if mutation.RowKey == \"\" || len(mutation.Ops) == 0 {\n\treturn fmt.Errorf(\"invalid mutation: empty row key or no ops\")\n}","typeGuard":null,"tryCatchPattern":"if err := f.table.Apply(ctx, mutation.RowKey, m); err != nil {\n\tif isTransientGRPC(err) { /* retry with backoff */ }\n\treturn fmt.Errorf(\"row %q: %w\", mutation.RowKey, err)\n}","preventionTips":["Grant roles/bigtable.user to the pipeline's service account","Validate row keys (non-empty, size limits) before emitting Mutations","Prefer the batch write path for high-volume writes and configure retries for transient gRPC codes"],"tags":["gcp","bigtable","write-failed","beam-io"],"backgroundTag":"database-write-failed","analyzedSha":"12126d8942aaf848030c478b4c6a28c6af861c66","analyzedAt":"2026-09-13T01:50:10.254Z","contentChangedAt":"2026-09-13T01:50:10.254Z","schemaVersion":2},"datasetVersion":"2026-09-20T03:17:13.778Z"}