apache/beam · error · IllegalArgumentException

Collection element type cannot be null for type: " +…

Error message

Collection element type cannot be null for type: " + fieldType

What it means

When converting a BSON iterable/array into a Beam Row list, convertFromBsonValue needs the collection's element type from the schema FieldType. If fieldType.getCollectionElementType() returns null, the converter cannot know how to convert elements and throws this IllegalArgumentException.

Solutions

Define the array field with an explicit element type in the schema (e.g., ARRAY<STRING> not bare ARRAY)
Rebuild the schema using Schema.Field.of(name, FieldType.array(FieldType.string())) so elementType is non-null
Avoid raw/unparameterized collection types when generating the schema

Example fix

// before
Schema.Field.of("items", FieldType.array(null)); // elementType null -> throws
// after
Schema.Field.of("items", FieldType.array(FieldType.STRING));

Defensive patterns

Strategy: validation

Validate before calling

FieldType ft = schema.getField("items").getType();
if ((ft.getTypeName() == Schema.TypeName.ARRAY || ft.getTypeName() == Schema.TypeName.ITERABLE)
    && ft.getCollectionElementType() == null) {
  throw new IllegalArgumentException("Array field 'items' must declare an element type");
}

Type guard

static boolean hasElementType(FieldType fieldType) {
  return fieldType.getCollectionElementType() != null;
}

Try / catch

try {
  Row row = MongoDbUtils.toRow(doc, schema);
} catch (IllegalArgumentException e) {
  if (e.getMessage().startsWith("Collection element type cannot be null")) {
    // rebuild schema with explicit element types
  }
}

Prevention

Always parameterize array/iterable schema fields with a concrete element FieldType
Avoid raw collection types in POJOs used for schema inference
Validate programmatically built schemas (all collection fields have element types) before use

When it happens

Trigger: A Beam schema field declared as ARRAY/ITERABLE without a concrete element type (missing type parameter / null collection element type) encountered during BSON-to-Row conversion.

Common situations: Programmatically built schemas where the collection element type was never set, or reflection-based schema inference failing to resolve the element generic type.

Understand the failure class

Background: "missing required argument" and "the following required arguments were not provided": what required-argument errors mean and how to fix them — this error's family across 20 libraries.

Related errors

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

Appendix: source

Thrown at sdks/java/io/mongodb/src/main/java/org/apache/beam/sdk/io/mongodb/MongoDbUtils.java:164

        } else if (value instanceof byte[]) {
          return (byte[]) value;
        } else {
          return value.toString().getBytes(java.nio.charset.StandardCharsets.UTF_8);
        }
      case ARRAY:
      case ITERABLE:
        if (!(value instanceof Iterable)) {
          throw new IllegalArgumentException(
              "Expected Iterable for type "
                  + fieldType
                  + ", but got: "
                  + value.getClass().getName());
        }
        Iterable<?> iterable = (Iterable<?>) value;
        List<@Nullable Object> rowList = new ArrayList<>();
        FieldType elementType = fieldType.getCollectionElementType();
        if (elementType == null) {
          throw new IllegalArgumentException(
              "Collection element type cannot be null for type: " + fieldType);
        }
        for (Object item : iterable) {
          rowList.add(convertFromBsonValue(item, elementType));
        }
        return rowList;
      case MAP:
        if (!(value instanceof Map)) {
          throw new IllegalArgumentException(
              "Expected Map for type " + fieldType + ", but got: " + value.getClass().getName());
        }
        Map<?, ?> map = (Map<?, ?>) value;
        Map<String, @Nullable Object> rowMap = new HashMap<>();
        FieldType valueType = fieldType.getMapValueType();
        if (valueType == null) {
          throw new IllegalArgumentException(
              "Map value type cannot be null for type: " + fieldType);
        }

View on GitHub (pinned to 12126d8942)