apache/beam · error · RuntimeException

Inputted Schema caused mutation error, check error logs and

Error message

Inputted Schema caused mutation error, check error logs and input schema format

What it means

BigtableWriteSchemaTransformProvider.expand sets bigtableMutations via changeMutationInput, which can return null when the input rows fail mutation conversion (a per-row error was logged upstream). If the resulting value is null, expand throws this RuntimeException telling the user to check the error logs and the schema format.

Source

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

                + "\"column_qualifier\": ByteString\n"
                + "\"family_name\": String\n"
                + "\"timestamp_micros\": Long\n"
                + "\"start_timestamp_micros\": Long\n"
                + "\"end_timestamp_micros\": Long\n"
                + "\nOR\n"
                + "\n"
                + "\"key\": ByteString\n"
                + "(\"mutations\", contains map(String, ByteString) of mutations in the mutation schema format");
      }

      if (bigtableMutations != null) {
        bigtableMutations.apply(
            BigtableIO.write()
                .withTableId(configuration.getTableId())
                .withInstanceId(configuration.getInstanceId())
                .withProjectId(configuration.getProjectId()));
      } else {
        throw new RuntimeException(
            "Inputted Schema caused mutation error, check error logs and input schema format");
      }
      return PCollectionRowTuple.empty(input.getPipeline());
    }

    private void validateField(Schema inputSchema, String field, Schema.TypeName expectedType) {
      Schema.TypeName actualType = inputSchema.getField(field).getType().getTypeName();
      checkState(
          actualType.equals(expectedType),
          "Schema field '%s' should be of type %s, but was %s.",
          field,
          expectedType,
          actualType);
    }

    public PCollection<KV<ByteString, Iterable<Mutation>>> changeMutationInput(
        PCollectionRowTuple inputR) {
      PCollection<Row> beamRowMutationsList = inputR.getSinglePCollection();

View on GitHub (pinned to 12126d8942)

Solutions

1. Read the error logs emitted during changeMutationInput to find which rows/fields failed
2. Fix the input rows' schema/values to conform to the mutation schema format
3. Pre-validate the 'type' values in your data before applying the transform
4. Filter or transform bad records upstream before feeding the Bigtable transform

Example fix

// before
PCollection<Row> rows = readRows(); // some rows have type=null
rows.apply(BigtableWriteSchemaTransformProvider...) // throws
// after
PCollection<Row> rows = readRows()
    .apply(Filter.by(r -> r.getString("type") != null));

boolean allRowsValid(PCollection<Row> rows) {
  return rows.apply(Filter.by(r -> r.getString("type") != null
      && Set.of("SetCell","DeleteFamily","DeleteColumn","DeleteRow")
           .contains(r.getString("type")))) != null;
}

When it happens

Trigger: Applying the Bigtable write schema transform where one or more input rows have invalid mutation data (bad 'type' value, missing required fields), causing changeMutationInput to fail overall and return null.

Common situations: Upstream data producing rows whose 'type' field isn't one of SetCell/DeleteFamily/DeleteColumn/DeleteRow; malformed timestamps or missing family_name in a batch of rows.

Understand the failure class

Background: Schema validation failed / invalid input schema: payload rejected because its shape doesn't match the expected schema — this error's family across 28 libraries.

Related errors

• Input Schema is invalid: Schema should be formatted in one
• Mutation type cannot be null.
• Unexpected mutation type [%s]: Key value is %s
• Unexpected mutation type [%s]: %s
• Schema has to contain '%s' field

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