apache/beam · error · IllegalArgumentException

Element argument type {} does not work with expected schema

Error message

Element argument type {} does not work with expected schema field type {}

What it means

getConvertPrimitive validates that the element argument's output type descriptor corresponds exactly to the schema field type it will populate. StaticSchemaInference re-infers the FieldType from the type descriptor, and any mismatch (e.g. logical vs primitive, different nullability, DATETIME vs LONG) throws IllegalArgumentException. This guards against silently inserting a wrong-typed converter.

Source

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

                + 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,
      TypeConversionsFactory typeConversionsFactory) {
    FieldType expectedFieldType =
        StaticSchemaInference.fieldFromType(outputTypeDescriptor, JavaFieldTypeSupplier.INSTANCE);
    if (!expectedFieldType.equals(fieldType)) {
      throw new IllegalArgumentException(
          "Element argument type "
              + outputTypeDescriptor
              + " does not work with expected schema field type "
              + fieldType);
    }

    Type expectedInputType =
        typeConversionsFactory.createTypeConversion(false).convert(outputTypeDescriptor);

    TypeDescriptor<?> outputType = outputTypeDescriptor;
    if (outputType.getRawType().isPrimitive()) {
      // A SerializableFunction can only return an Object type, so if the DoFn parameter is a
      // primitive type, then box it for the return. The return type will be unboxed before being
      // forwarded to the DoFn parameter.
      outputType = TypeDescriptor.of(Primitives.wrap(outputType.getRawType()));
    }

    TypeDescription.Generic genericType =

View on GitHub (pinned to 12126d8942)

Solutions

1. Change the conversion's TypeDescriptor/generic type so it matches the field type exactly (e.g. use Long for INT64 fields).
2. Or update the schema field type to match the element argument type.
3. If using a logical type, ensure the element descriptor maps to the same FieldType (same logical type identifier).

Example fix

// before
.apply("id", Convert.from(Integer.class)) // field is INT64
// after
.apply("id", Convert.from(Long.class))

FieldType expected = StaticSchemaInference.fieldFromType(TypeDescriptor.of(Integer.class), JavaFieldTypeSupplier.INSTANCE);
if (!expected.equals(schema.getField("id").getType())) { /* fix conversion type or field type */ }

static <T> boolean matchesFieldType(TypeDescriptor<T> d, FieldType f) { return StaticSchemaInference.fieldFromType(d, JavaFieldTypeSupplier.INSTANCE).equals(f); }

try { applyConvert(...); } catch (IllegalArgumentException e) { if (e.getMessage().contains("does not work with expected schema field type")) { /* align types */ } throw e; }

When it happens

Trigger: Registering a primitive field conversion where the Java element type (e.g. Integer vs Long, String vs Instant) does not produce the same FieldType as the schema field; mismatched logical-type wrappers.

Common situations: Changing a schema field from INTEGER to INT64 without updating the conversion lambda's type; using java.util.Date where Beam expects Instant; annotation Schema mismatches between declared and actual types.

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

• Cannot convert between types that don't have equivalent sche
• 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/3475111af2da57cd. Report an issue: GitHub.