apache/beam · error · RuntimeException

Cannot convert between types that don't have equivalent sche

Error message

Cannot convert between types that don't have equivalent schemas. input schema: ${checkedSchema} output schema: ${outputSchema}

What it means

ConvertHelpers.getConvertedSchemaInformation only supports conversions between types whose schemas are equivalent (possibly after primitive boxing/unboxing). If the resolved input schema still differs from the output schema, no conversion function exists and Beam throws RuntimeException. Cross-schema conversion is intentionally unsupported in this helper.

Source

Thrown at sdks/java/core/src/main/java/org/apache/beam/sdk/schemas/utils/ConvertHelpers.java:137

      LOG.debug("No schema found for type {}", outputType, e);
    }
    FieldType unboxedType = null;
    // TODO: Properly handle nullable.
    if (outputSchema == null || !outputSchema.assignableToIgnoreNullable(inputSchema)) {
      // The schema is not convertible directly. Attempt to unbox it and see if the schema matches
      // then.
      Schema checkedSchema = inputSchema;
      if (inputSchema.getFieldCount() == 1) {
        unboxedType = inputSchema.getField(0).getType();
        if (unboxedType.getTypeName().isCompositeType()
            && !outputSchema.assignableToIgnoreNullable(unboxedType.getRowSchema())) {
          checkedSchema = unboxedType.getRowSchema();
        } else {
          checkedSchema = null;
        }
      }
      if (checkedSchema != null) {
        throw new RuntimeException(
            "Cannot convert between types that don't have equivalent schemas."
                + " input schema: "
                + checkedSchema
                + " output schema: "
                + outputSchema);
      }
    }
    return new ConvertedSchemaInformation<>(outputSchemaCoder, unboxedType);
  }

  /**
   * Returns a function to convert a Row into a primitive type. This only works when the row schema
   * contains a single field, and that field is convertible to the primitive type.
   */
  @SuppressWarnings("unchecked")
  public static <OutputT> SerializableFunction<?, OutputT> getConvertPrimitive(
      FieldType fieldType,
      TypeDescriptor<?> outputTypeDescriptor,

View on GitHub (pinned to 12126d8942)

Solutions

1. Make the two types' schemas identical (same field names, types, order, nullability) — align the classes.
2. Insert an explicit map/Select step that reshapes the row field-by-field instead of relying on implicit conversion.
3. Use SchemaUtil/ConvertHelpers only for genuinely equivalent schemas; convert primitives via boxing-compatible types.

Example fix

// before: two classes with differing field names -> conversion throws
// after: explicit map
rows.apply(MapElements.into(TypeDescriptor.of(NewType.class)).via(old -> new NewType(old.id, old.name)));

Schema in = SchemaUtil.schemaOf(OldType.class); Schema out = SchemaUtil.schemaOf(NewType.class);
if (!in.equivalent(out)) throw new IllegalArgumentException("Schemas differ: align fields or use explicit map");

try { rows.setRow(NewType.class); } catch (RuntimeException e) { if (e.getMessage().startsWith("Cannot convert between types")) { /* insert explicit MapElements */ } throw e; }

When it happens

Trigger: Calling setRow/convert between two schema types whose inferred schemas differ (different field names, types, ordering, or nullability); passing a boxed type whose row schema doesn't equal the target output schema.

Common situations: Evolving a POJO/AutoValue class (adding/renaming a field) and then converting old-type rows to the new type; mapping between two structurally different classes that share some fields; copying code between classes with reordered fields.

Understand the failure class

Background: "is not a compatible type" / "cannot merge" errors: when a value's type doesn't match what the library requires — this error's family across 65 libraries.

Related errors

• Element argument type {} does not work with expected schema
• The input schema must have exactly one field of type byte.
• FieldType unexpected +fieldType.getTypeName()
• Cannot merge two types: +fieldType1.getTypeName()+ and +fiel
• value type is '%s' for field type '%s'

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