apache/beam · error · IllegalArgumentException

value type is '%s' for field type '%s'

Error message

value type is '%s' for field type '%s'

What it means

toPrettyFieldValueString formats a field's value for display; for ARRAY/ITERABLE field types it expects the value to be a java.util.List. If the runtime value class is not a List it throws IllegalArgumentException formatted as "value type is '%s' for field type '%s'". It means the value's runtime type does not match the declared field type of the schema/row.

Source

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

      case DOUBLE:
      case DATETIME:
      case BOOLEAN:
        return Objects.toString(value);
      case STRING:
        {
          String string = (String) value;
          return "\"" + string.replace("\\", "\\\\").replace("\"", "\\\"") + "\"";
        }
      case BYTES:
        {
          byte[] bytes = (byte[]) value;
          return Arrays.toString(bytes);
        }
      case ARRAY:
      case ITERABLE:
        {
          if (!(value instanceof List)) {
            throw new IllegalArgumentException(
                String.format(
                    "value type is '%s' for field type '%s'",
                    value.getClass(), fieldType.getTypeName()));
          }
          FieldType elementType = Objects.requireNonNull(fieldType.getCollectionElementType());

          @SuppressWarnings("unchecked")
          List<Object> list = (List<Object>) value;
          if (list.isEmpty()) {
            return "[]";
          }
          StringBuilder sb = new StringBuilder();
          sb.append("[\n");
          int size = list.size();
          int index = 0;
          for (Object element : list) {
            sb.append(nextPrefix)
                .append(toPrettyFieldValueString(elementType, element, nextPrefix));

View on GitHub (pinned to 12126d8942)

Solutions

1. Materialize collection values into java.util.List before building the Row (e.g. ImmutableList.copyOf(iterable)).
2. Verify the Row's value order/types matches the schema field order; fix the add-value calls.
3. Check the producer/coder that generated the value so ARRAY/ITERABLE fields always carry List values.
4. Catch IllegalArgumentException and inspect value.getClass() vs fieldType.getTypeName() to locate the misaligned field.

Example fix

// before
Row row = Row.withSchema(schema).addValues(myIterableNonList, "x").build();
String out = SchemaUtils.toPrettyRowString(row, schema); // throws
// after
Row row = Row.withSchema(schema)
    .addValues(ImmutableList.copyOf(myIterableNonList), "x") // array fields must be List
    .build();
String out = SchemaUtils.toPrettyRowString(row, schema);

for (int i = 0; i < schema.getFieldCount(); i++) {
  Field f = schema.getField(i);
  Object v = row.getValue(i);
  if ((f.getType().getTypeName() == TypeName.ARRAY
       || f.getType().getTypeName() == TypeName.ITERABLE)
      && !(v instanceof List)) {
    throw new IllegalStateException("Field " + f.getName() + " value is not a List: "
        + (v == null ? "null" : v.getClass()));
  }
}

boolean isListValueForField(Object value, FieldType type) {
  return (type.getTypeName() != TypeName.ARRAY && type.getTypeName() != TypeName.ITERABLE)
      || value instanceof List;
}

try {
  String out = SchemaUtils.toPrettyRowString(row, schema);
} catch (IllegalArgumentException e) {
  if (e.getMessage().contains("for field type")) {
    LOG.error("Row value type does not match schema field type: {}", e.getMessage());
    throw new RowFormatException(e);
  }
  throw e;
}

When it happens

Trigger: Calling SchemaUtils.toPrettyRowString(row, schema) (or toPrettyOptionsString/toPrettyFieldValueString directly) where an ARRAY or ITERABLE field carries a value that is not a List — e.g. a lazily-converted iterable object, a custom Iterable implementation, or a Row built with a misaligned value/type order.

Common situations: Constructing a Row manually with values in the wrong order so an array field receives a scalar (or a non-List collection); a custom Coder/adapter producing Iterable-backed values instead of materialized Lists; schema registry drift where the declared type says ARRAY but the producer emitted something else.

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

• The input schema must have exactly one field of type byte.
• Cannot merge two types: +fieldType1.getTypeName()+ and +fiel
• Unreachable case for Beam typename %s
• Problem converting field %s expected type: %s
• Unable to provide coder for %s, this factory can only provid

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