{"record":{"id":"3c10794100168c85","repo":"apache/beam","slug":"unexpected-mutation","errorCode":null,"errorMessage":"Unexpected mutation","messagePattern":"Unexpected mutation","errorType":"exception","errorClass":"ValueError","httpStatus":null,"severity":"error","filePath":"sdks/python/apache_beam/io/gcp/bigtableio.py","lineNumber":325,"sourceCode":"              \"column_qualifier\": mutation.delete_from_column.column_qualifier\n          }\n          time_range = mutation.delete_from_column.time_range\n          if time_range.start_timestamp_micros:\n            mutation_dict['start_timestamp_micros'] = struct.pack(\n                '>q', time_range.start_timestamp_micros)\n          if time_range.end_timestamp_micros:\n            mutation_dict['end_timestamp_micros'] = struct.pack(\n                '>q', time_range.end_timestamp_micros)\n        elif mutation.__contains__(\"delete_from_family\"):\n          mutation_dict = {\n              \"type\": b'DeleteFromFamily',\n              \"family_name\": mutation.delete_from_family.family_name.encode(\n                  'utf-8')\n          }\n        elif mutation.__contains__(\"delete_from_row\"):\n          mutation_dict = {\"type\": b'DeleteFromRow'}\n        else:\n          raise ValueError(\"Unexpected mutation\")\n\n        args[\"mutations\"].append(mutation_dict)\n\n      yield beam.Row(**args)\n\n\nclass ReadFromBigtable(PTransform):\n  \"\"\"Reads rows from Bigtable.\n\n  Returns a PCollection of PartialRowData objects, each representing a\n  Bigtable row. For more information about this row object, visit\n  https://cloud.google.com/python/docs/reference/bigtable/latest/row#class-googlecloudbigtablerowpartialrowdatarowkey\n  \"\"\"\n  URN = \"beam:schematransform:org.apache.beam:bigtable_read:v1\"\n\n  def __init__(self, project_id, instance_id, table_id, expansion_service=None):\n    \"\"\"Initialize a ReadFromBigtable transform.\n","sourceCodeStart":307,"sourceCodeEnd":343,"githubUrl":"https://github.com/apache/beam/blob/12126d8942aaf848030c478b4c6a28c6af861c66/sdks/python/apache_beam/io/gcp/bigtableio.py#L307-L343","documentation":"WriteToBigTable's process() converts each mutation dict into a form suitable for the BigTable Write API and raises ValueError for mutation types it does not recognize. Only SetCell, DeleteFromColumn, DeleteFromFamily, and DeleteFromRow are accepted.","triggerScenarios":"A PCollection element's mutation dict lacks any of the recognized keys (set_cell, delete_from_column, delete_from_family, delete_from_row), e.g. a typo like 'DeleteFromRow' vs expected key, or a mutation constructed manually with wrong keys.","commonSituations":"Building mutations by hand for WriteToBigTable with incorrect key names; passing raw protobuf Mutation objects instead of dicts; Beam version differences in accepted mutation dict key formats.","solutions":["Use beam.Row / the documented mutation dict keys exactly: set_cell, delete_from_column, delete_from_family, delete_from_row.","Validate each mutation dict has one recognized key before writing to the sink.","Prefer constructing mutations via the documented helpers rather than hand-built dicts."],"exampleFix":"// before\nrow = {\"delete_from_row\": True, \"unknown_op\": 1}  # ValueError: Unexpected mutation\n\n// after\nrow = {\"delete_from_row\": True}  # exactly one recognized mutation key","handlingStrategy":"validation","validationCode":"VALID = {'set_cell', 'delete_from_column', 'delete_from_family', 'delete_from_row'}\nfor m in mutations:\n    if not (set(m.keys()) & VALID):\n        raise ValueError(f'mutation missing a recognized key: {m.keys()}')","typeGuard":"def is_valid_mutation(m):\n    return isinstance(m, dict) and bool({'set_cell','delete_from_column','delete_from_family','delete_from_row'} & set(m.keys()))","tryCatchPattern":"try:\n    result = pipeline | WriteToBigTable(project_id=..., instance_id=..., table_id=...)\nexcept ValueError as e:\n    if str(e) == 'Unexpected mutation':\n        log.error('bad mutation dict in PCollection: check mutation keys')\n    else:\n        raise","preventionTips":["Build mutations with the documented dict keys exactly; never hand-roll alternate key names.","Unit-test mutation-producing DoFns against the four accepted mutation kinds.","Validate mutation dicts before sending them into WriteToBigTable."],"tags":["python","apache-beam","bigtable","mutation","validation"],"backgroundTag":"invalid-enum-value","analyzedSha":"12126d8942aaf848030c478b4c6a28c6af861c66","analyzedAt":"2026-09-13T01:50:10.254Z","contentChangedAt":"2026-09-13T01:50:10.254Z","schemaVersion":2},"datasetVersion":"2026-09-14T21:17:11.552Z"}