apache/beam · error · IllegalArgumentException

Collection element type cannot be null.

Error message

Collection element type cannot be null.

What it means

javaToValue converts Java objects to Firestore Value protos using the Beam schema FieldType. When the field is ARRAY or ITERABLE, the element type from fieldType.getCollectionElementType() is required to recursively convert items; if it is null the converter refuses and throws IllegalArgumentException, because it cannot know how to serialize the elements.

Source

Thrown at sdks/java/io/google-cloud-platform/src/main/java/org/apache/beam/sdk/io/gcp/firestore/FirestoreUtils.java:180

      case INT64:
        return Value.newBuilder().setIntegerValue(((Number) value).longValue()).build();
      case DOUBLE:
        return Value.newBuilder().setDoubleValue(((Number) value).doubleValue()).build();
      case BOOLEAN:
        return Value.newBuilder().setBooleanValue((Boolean) value).build();
      case DATETIME:
        Instant instant = (Instant) value;
        return Value.newBuilder()
            .setTimestampValue(Timestamps.fromMillis(instant.getMillis()))
            .build();
      case BYTES:
        return Value.newBuilder().setBytesValue(ByteString.copyFrom((byte[]) value)).build();
      case ARRAY:
      case ITERABLE:
        ArrayValue.Builder arrayBuilder = ArrayValue.newBuilder();
        FieldType elementType = fieldType.getCollectionElementType();
        if (elementType == null) {
          throw new IllegalArgumentException("Collection element type cannot be null.");
        }
        for (Object item : (Iterable<?>) value) {
          arrayBuilder.addValues(
              item == null
                  ? Value.newBuilder()
                      .setNullValue(com.google.protobuf.NullValue.NULL_VALUE)
                      .build()
                  : javaToValue(item, elementType));
        }
        return Value.newBuilder().setArrayValue(arrayBuilder.build()).build();
      case MAP:
        MapValue.Builder mapBuilder = MapValue.newBuilder();
        FieldType valueType = fieldType.getMapValueType();
        if (valueType == null) {
          throw new IllegalArgumentException("Map value type cannot be null.");
        }
        for (Map.Entry<?, ?> entry : ((Map<?, ?>) value).entrySet()) {
          Object mapValue = entry.getValue();

View on GitHub (pinned to 12126d8942)

Solutions

1. Create array fields with FieldType.iterable(FieldType) supplying a concrete element type
2. Verify the Schema's field types with field.getType().getCollectionElementType() before writing
3. Use Schema.builder().addArrayField(name, elementType) rather than manual FieldType construction

Example fix

// before
FieldType bad = FieldType.of(TypeName.ARRAY); // no element type
// after
FieldType good = FieldType.iterable(FieldType.STRING);

FieldType ft = schema.getField(name).getType();
if ((ft.getTypeName() == TypeName.ARRAY || ft.getTypeName() == TypeName.ITERABLE)
    && ft.getCollectionElementType() == null) {
  throw new IllegalStateException("Array field '" + name + "' lacks element type");
}

When it happens

Trigger: Writing Rows to Firestore where a field was declared as an array/iterable type but its FieldType was constructed without an element type — e.g. FieldType.iterable(...) composed incorrectly or a programmatically built FieldType missing element metadata.

Common situations: Building schemas dynamically with reflection and forgetting to specify the element type; schemas created from deserialized/incomplete type metadata; using FieldType.of(TypeName.ARRAY) directly instead of FieldType.iterable(elementType).

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

• Document id field '{documentIdField}' must be set on input r
• Map value type cannot be null.
• Row schema cannot be null.
• Cast isn't compatible using +validator()+: +reason
• Invalid Firestore document name: {documentName}

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