apache/beam · error · RuntimeException

Unexpected mutation type [%s]: Key value is %s

Error message

Unexpected mutation type [%s]: Key value is %s

What it means

In changeMutationInput, after checking the known mutation types (SetCell, DeleteFamily, etc.), the default branch throws a RuntimeException formatted with the unrecognized type and the row's key. This catches any 'type' string outside the supported set.

Source

Thrown at sdks/java/io/google-cloud-platform/src/main/java/org/apache/beam/sdk/io/gcp/bigtable/BigtableWriteSchemaTransformProvider.java:355

                            bigtableMutation =
                                Mutation.newBuilder()
                                    .setDeleteFromFamily(
                                        Mutation.DeleteFromFamily.newBuilder()
                                            .setFamilyName(
                                                Preconditions.checkStateNotNull(
                                                    input.getString("family_name"),
                                                    "Encountered DeleteFromFamily mutation with null 'family_name' property."))
                                            .build())
                                    .build();
                            break;
                          case "DeleteFromRow":
                            bigtableMutation =
                                Mutation.newBuilder()
                                    .setDeleteFromRow(Mutation.DeleteFromRow.newBuilder().build())
                                    .build();
                            break;
                          default:
                            throw new RuntimeException(
                                String.format(
                                    "Unexpected mutation type [%s]: Key value is %s",
                                    input.getString("type"),
                                    Arrays.toString(input.getBytes("key"))));
                        }
                        return KV.of(key, bigtableMutation);
                      }));
      // now we need to make the KV into a PCollection of KV<ByteString, Iterable<Mutation>>
      return changedBeamRowMutationsList.apply(GroupByKey.create());
    }
  }

  public static class GetMutationsFromBeamRow
      extends SimpleFunction<Row, KV<ByteString, Iterable<Mutation>>> {
    @Override
    public KV<ByteString, Iterable<Mutation>> apply(Row row) {
      ByteString key = ByteString.copyFrom(ofNullable(row.getBytes("key")).get());
      List<Map<String, byte[]>> beamRowMutations =

View on GitHub (pinned to 12126d8942)

Solutions

1. Use exactly one of: SetCell, DeleteFamily, DeleteColumn, DeleteRow for the 'type' value (case-sensitive)
2. Normalize the type string upstream (e.g. map HBase 'Put' to 'SetCell')
3. Check the key value printed in the error to identify the offending record and fix or drop it

Example fix

// before
row.get("type") == "put" // unsupported
// after
row.get("type") == "SetCell" // supported, case-sensitive

Set<String> VALID = Set.of("SetCell","DeleteFamily","DeleteColumn","DeleteRow");
boolean validType(Row row) {
  String t = row.getString("type");
  return t != null && VALID.contains(t);
}

boolean isKnownMutationType(Row row) {
  String t = row.getString("type");
  return "SetCell".equals(t) || "DeleteFamily".equals(t)
      || "DeleteColumn".equals(t) || "DeleteRow".equals(t);
}

When it happens

Trigger: A row whose 'type' field is a non-null string that isn't exactly one of SetCell, DeleteFamily, DeleteColumn, DeleteRow — e.g. 'setcell' (wrong case), 'SET_CELL', 'put', or arbitrary garbage data.

Common situations: Data sourced from systems with different mutation vocabularies (e.g. HBase 'Put'/'Delete' verbs); case-sensitivity bugs; users inventing new type names expecting support.

Understand the failure class

Background: Invalid enum value errors: "Unknown type", "Invalid scope", "must be one of" — when a string is not on the library's allowed list — this error's family across 23 libraries.

Related errors

• Unexpected mutation type [%s]: %s
• Inputted Schema caused mutation error, check error logs and
• Mutation type cannot be null.
• Unexpected mutation
• one instance of bigtableio.Mutation must not have more than

AI-assisted analysis of apache/beam@12126d8942 (2026-09-13). Data as JSON: /api/errors/7404338808b00142. Report an issue: GitHub.