apache/beam · error · RuntimeException

Collection parameter is not parameterized!

Error message

Collection parameter is not parameterized!

What it means

ReflectUtils.getIterableComponentType extracts the element TypeDescriptor of a collection-typed field. If the field's reflective type is not a ParameterizedType (i.e. the collection is used as a raw type with no generic parameter), it throws this RuntimeException, because Beam cannot infer the element schema without the type parameter.

Source

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

  /** For an array T[] or a subclass of Iterable<T>, return a TypeDescriptor describing T. */
  public static @Nullable TypeDescriptor getIterableComponentType(TypeDescriptor valueType) {
    TypeDescriptor componentType = null;
    if (valueType.isArray()) {
      Type component = valueType.getComponentType().getType();
      if (!component.equals(byte.class)) {
        // Byte arrays are special cased since we have a schema type corresponding to them.
        componentType = TypeDescriptor.of(component);
      }
    } else if (valueType.isSubtypeOf(TypeDescriptor.of(Iterable.class))) {
      TypeDescriptor<Iterable<?>> collection = valueType.getSupertype(Iterable.class);
      if (collection.getType() instanceof ParameterizedType) {
        ParameterizedType ptype = (ParameterizedType) collection.getType();
        java.lang.reflect.Type[] params = ptype.getActualTypeArguments();
        checkArgument(params.length == 1);
        componentType = TypeDescriptor.of(params[0]);
      } else {
        throw new RuntimeException("Collection parameter is not parameterized!");
      }
    }
    return componentType;
  }

  public static TypeDescriptor getMapType(TypeDescriptor valueType, int index) {
    TypeDescriptor mapType = null;
    if (valueType.isSubtypeOf(TypeDescriptor.of(Map.class))) {
      TypeDescriptor<Collection<?>> map = valueType.getSupertype(Map.class);
      if (map.getType() instanceof ParameterizedType) {
        ParameterizedType ptype = (ParameterizedType) map.getType();
        java.lang.reflect.Type[] params = ptype.getActualTypeArguments();
        mapType = TypeDescriptor.of(params[index]);
      } else {
        throw new RuntimeException("Map type is not parameterized! " + map);
      }
    }
    return mapType;

View on GitHub (pinned to 12126d8942)

Solutions

1. Parameterize the field type: List<String> instead of raw List.
2. If the type is only available as a Class, provide a TypeDescriptor with explicit generics when registering the schema.
3. Override schema inference by supplying an explicit Schema and coders for the field instead of relying on reflection.

Example fix

// before
private List items; // raw type
// after
private List<String> items;

TypeDescriptor<?> td = TypeDescriptor.of(MyPojo.class).getField("items").getType();
if (Collection.class.isAssignableFrom(td.getRawType()) && !(td.getType() instanceof java.lang.reflect.ParameterizedType)) {
  throw new IllegalStateException("Collection field must declare its element type");
}

// returns the element descriptor, or null when the collection is raw (would trigger the error)
static <C extends Collection<?>> TypeDescriptor<?> elementOrNull(TypeDescriptor<C> td) {
  return td.getType() instanceof java.lang.reflect.ParameterizedType
      ? td.resolveType(java.util.Arrays.stream(((java.lang.reflect.ParameterizedType) td.getType()).getActualTypeArguments()).findFirst().orElse(null))
      : null;
}

When it happens

Trigger: A POJO/schema field declared as raw List, raw Iterable, or raw Collection (no <T> type argument) while Beam infers its schema via ReflectUtils.getIterableComponentType.

Common situations: Legacy Java code with raw collection types, fields typed as List (raw) to avoid warnings suppression, or generic type info erased by declaring the field through reflection-obtained raw Classes rather than parameterized 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

• Map type is not parameterized! {}
• Could not determine array parameter type for field.
• Cound not determine array parameter type for field.
• Was not able to generate getters for schema: {} class: {}
• Unable to generate a creator for POJO '%s' with inferred sch

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