apache/beam · error · IllegalArgumentException

Failed to print mod: {row}

Error message

Failed to print mod: {row}

What it means

modFrom converts a JSON row's KEYS/OLD_VALUES/NEW_VALUES columns into a Mod object using the protobuf JSON printer. If printing any of these Value maps throws InvalidProtocolBufferException, the mapper throws 'Failed to print mod'. The row does not conform to the expected change stream mod structure.

Source

Thrown at sdks/java/io/google-cloud-platform/src/main/java/org/apache/beam/sdk/io/gcp/spanner/changestreams/mapper/ChangeStreamRecordMapper.java:734

          this.printer.print(
              Optional.ofNullable(valueMap.get(KEYS_COLUMN))
                  .orElseThrow(IllegalArgumentException::new));

      final String oldValues =
          !valueMap.containsKey("old_values")
              ? null
              : this.printer.print(
                  Optional.ofNullable(valueMap.get(OLD_VALUES_COLUMN))
                      .orElseThrow(IllegalArgumentException::new));
      final String newValues =
          !valueMap.containsKey("new_values")
              ? null
              : this.printer.print(
                  Optional.ofNullable(valueMap.get(NEW_VALUES_COLUMN))
                      .orElseThrow(IllegalArgumentException::new));
      return new Mod(keys, oldValues, newValues);
    } catch (InvalidProtocolBufferException exc) {
      throw new IllegalArgumentException("Failed to print mod: " + row);
    }
  }

  private ModType modTypeFrom(String name) {
    try {
      return ModType.valueOf(name);
    } catch (IllegalArgumentException e) {
      // This is not logged to prevent flooding users with messages
      return ModType.UNKNOWN;
    }
  }

  private ValueCaptureType valueCaptureTypeFrom(String name) {
    try {
      return ValueCaptureType.valueOf(name);
    } catch (IllegalArgumentException e) {
      // This is not logged to prevent flooding users with messages
      return ValueCaptureType.UNKNOWN;

View on GitHub (pinned to 12126d8942)

Solutions

1. Ensure KEYS/OLD_VALUES/NEW_VALUES entries are valid proto-JSON Values parsed with this.parser before mapping.
2. Check which of oldValues/newValues is null vs missing — provide the expected Value map or adjust nullability handling.
3. Confirm the row format matches the Beam version's ChangeStreamRecordMapper expectations.
4. Add try-catch around mod extraction to log and skip bad rows.
5. Inspect the printed row in the message to identify the failing column.

Example fix

// before
Mod mod = mapper.modFrom(struct); // throws 'Failed to print mod'

// after
String keysJson = struct.getJson("Keys");
if (keysJson == null || !keysJson.trim().startsWith("{")) {
  throw new IllegalArgumentException("Invalid mod keys JSON: " + keysJson);
}
Mod mod = mapper.modFrom(struct);

boolean isPrintableMod(Struct struct) {
  String keys = struct.getJson("Keys");
  return keys != null && keys.trim().startsWith("{");
}

try {
  Mod mod = modFrom(struct);
} catch (IllegalArgumentException e) {
  LOG.error("Failed to map mod for row: %s", e.getMessage());
}

When it happens

Trigger: A row whose KEYS_COLUMN, OLD_VALUES_COLUMN, or NEW_VALUES_COLUMN contains Values that fail protobuf JSON printing, or a NEW_VALUES/OLD_VALUES entry missing (orElseThrow(IllegalArgumentException::new)) combined with a printer failure — surfaced from the modFrom path exercised by the ChangeStreamRecordMapper constructor's public flow.

Common situations: Hand-written unit-test fixtures with invalid mod JSON; rows written by a mismatched connector version; nullability mismatches between what the caller passes and what modFrom expects; corrupted Spanner metadata rows.

Understand the failure class

Background: json.Marshal / "failed to marshal" errors in Go: why "unsupported type" happens and how to fix it — this error's family across 22 libraries.

Related errors

• Failed to print type: {row}
• Failed to parse record into proto: {row}
• Could not encode message as bytes
• Failed to convert PipelineOptions to JSON
• Failed to parse DataStore key from bytes.

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