apache/beam · error · IllegalArgumentException

Map value type cannot be null.

Error message

Map value type cannot be null.

What it means

javaToValue converts Java Map values to Firestore MapValue protos using the FieldType's map value type. If fieldType.getMapValueType() returns null — meaning the schema field was declared as a map without specifying the value type — the converter cannot serialize entries and throws IllegalArgumentException.

Source

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

        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();
          mapBuilder.putFields(
              String.valueOf(entry.getKey()),
              mapValue == null
                  ? Value.newBuilder()
                      .setNullValue(com.google.protobuf.NullValue.NULL_VALUE)
                      .build()
                  : javaToValue(mapValue, valueType));
        }
        return Value.newBuilder().setMapValue(mapBuilder.build()).build();
      case ROW:
        Schema rowSchema = fieldType.getRowSchema();
        if (rowSchema == null) {
          throw new IllegalArgumentException("Row schema cannot be null.");
        }
        if (!(value instanceof Row)) {

View on GitHub (pinned to 12126d8942)

Solutions

1. Declare map fields with FieldType.map(FieldType keyType, FieldType valueType)
2. Validate getMapValueType() != null for all map fields before writing to Firestore
3. Build maps with Schema.builder().addMapField(name, keyType, valueType)

Example fix

// before
FieldType bad = FieldType.of(TypeName.MAP); // no value type
// after
FieldType good = FieldType.map(FieldType.STRING, FieldType.INT64);

FieldType ft = schema.getField(name).getType();
if (ft.getTypeName() == TypeName.MAP && ft.getMapValueType() == null) {
  throw new IllegalStateException("Map field '" + name + "' lacks value type");
}

When it happens

Trigger: Writing Rows with MAP-typed fields whose FieldType lacks map value metadata, e.g. FieldType.of(TypeName.MAP) or a hand-built FieldType without the value-type parameter.

Common situations: Dynamically generated schemas missing map value types; schemas round-tripped through serialization losing nested type info; using addMapField incorrectly or constructing map field types without FieldType.map(keyType, valueType).

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
• Collection element 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/6998d0ab787309c9. Report an issue: GitHub.