apache/beam · error · IllegalArgumentException

Cannot merge two types: +fieldType1.getTypeName()+ and +fiel

Error message

Cannot merge two types: +fieldType1.getTypeName()+ and +fieldType2.getTypeName()

What it means

widenNullableTypes computes the widened (nullable-if-either) FieldType for two field types and requires both to share the same TypeName (e.g. both STRING, both INT64). If the TypeNames differ it throws IllegalArgumentException. It is used by mergeWideningNullable and collection/key/value type merging, so any schema merge of mismatched field types hits this.

Source

Thrown at sdks/java/core/src/main/java/org/apache/beam/sdk/schemas/SchemaUtils.java:62

      throw new IllegalArgumentException(
          "Cannot merge schemas with different numbers of fields. "
              + "schema1: "
              + schema1
              + " schema2: "
              + schema2);
    }
    Schema.Builder builder = Schema.builder();
    for (int i = 0; i < schema1.getFieldCount(); ++i) {
      String name = schema1.getField(i).getName();
      builder.addField(
          name, widenNullableTypes(schema1.getField(i).getType(), schema2.getField(i).getType()));
    }
    return builder.build();
  }

  static FieldType widenNullableTypes(FieldType fieldType1, FieldType fieldType2) {
    if (fieldType1.getTypeName() != fieldType2.getTypeName()) {
      throw new IllegalArgumentException(
          "Cannot merge two types: "
              + fieldType1.getTypeName()
              + " and "
              + fieldType2.getTypeName());
    }

    FieldType result;
    switch (fieldType1.getTypeName()) {
      case ROW:
        result =
            FieldType.row(
                mergeWideningNullable(fieldType1.getRowSchema(), fieldType2.getRowSchema()));
        break;
      case ARRAY:
        FieldType arrayElementType =
            widenNullableTypes(
                fieldType1.getCollectionElementType(), fieldType2.getCollectionElementType());
        result = FieldType.array(arrayElementType);

View on GitHub (pinned to 12126d8942)

Solutions

Align the field types at each position so TypeNames match; convert the data (e.g. cast INT64 to STRING) before merging.
Build a new schema explicitly with Schema.builder() mapping types to the desired target type instead of widening.
Regenerate both schemas from the same, current class/Avro definition.
Catch IllegalArgumentException and compare fieldType.getTypeName() per field to find the first mismatch.

Example fix

// before
Schema merged = SchemaUtils.mergeWideningNullable(schemaIntId, schemaStringId); // throws
// after
Schema fixed = Schema.builder()
    .addStringField("id") // convert int-typed data to string first
    .build();
Schema merged = SchemaUtils.mergeWideningNullable(fixed, schemaStringId);

Defensive patterns

Strategy: validation

Validate before calling

boolean typesMatch = IntStream.range(0, Math.min(s1.getFieldCount(), s2.getFieldCount()))
    .allMatch(i -> s1.getField(i).getType().getTypeName()
        == s2.getField(i).getType().getTypeName());
if (typesMatch) {
  Schema merged = SchemaUtils.mergeWideningNullable(s1, s2);
}

Type guard

boolean sameTypeNameAt(Schema s1, Schema s2, int i) {
  return s1.getField(i).getType().getTypeName()
      == s2.getField(i).getType().getTypeName();
}

Try / catch

try {
  Schema merged = SchemaUtils.mergeWideningNullable(s1, s2);
} catch (IllegalArgumentException e) {
  LOG.error("FieldType TypeName mismatch: {}", e.getMessage());
  throw new SchemaMergeException(e);
}

Prevention

Keep a single schema definition (class/Avro) as the source of truth for both sides.
Convert field types explicitly before merging rather than relying on widening.
Pin Beam versions across pipeline stages so generated types don't drift.

When it happens

Trigger: Merging two schemas where the same-position fields have different TypeName values — e.g. schema1 field 'id' is INT64 while schema2's 'id' is STRING; also nested merges of array element types, iterable element types, or map key/value types with differing TypeNames.

Common situations: Upstream type change (column switched from int to string); one schema generated from Avro and the other from Java types with different mappings; versioned pipelines where a field's type was refactored between releases.

Understand the failure class

Background: Type mismatch errors: IllegalArgumentException, TypeError and type guards across 150 open-source libraries — this error's family across 150 libraries.

Related errors

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