What causes "Map value type cannot be null for type: " + fieldType" in apache/beam?

Declare the map value type explicitly: FieldType.map(FieldType.STRING) (or the appropriate value FieldType) when building the schema.

apache/beam · error · IllegalArgumentException

Map value type cannot be null for type: " + fieldType

Error message

Map value type cannot be null for type: " + fieldType

What it means

After confirming the value is a Map, convertFromBsonValue asks FieldType.getMapValueType() to know how to convert each map value. A MAP FieldType in Beam always has an element type; if this returns null the FieldType was constructed inconsistently (a map type with no declared value type), so conversion cannot proceed safely.

Solutions

Declare the map value type explicitly: FieldType.map(FieldType.STRING) (or the appropriate value FieldType) when building the schema.
If generics are erased, build the schema with an explicit Field list instead of relying on automatic schema inference from a raw Map class.
Verify the SchemaRegistry-generated schema (e.g. getSchema(Class)) resolves the Map's generic parameter; use TypeDescriptor with full generics.

Example fix

// before
FieldType t = FieldType.map(null);
// after
FieldType t = FieldType.map(FieldType.STRING);

Defensive patterns

Strategy: validation

Validate before calling

schema.getFields().forEach(f -> {
  if (f.getType().getTypeName().equals(TypeName.MAP) && f.getType().getMapValueType() == null) {
    throw new IllegalStateException("MAP field without value type: " + f.getName());
  }
});

Try / catch

try {
  Row row = toRow(doc, schema);
} catch (IllegalArgumentException e) {
  if (e.getMessage() != null && e.getMessage().contains("Map value type cannot be null")) {
    throw new SchemaConfigurationException("Declare map value types explicitly");
  }
  throw e;
}

Prevention

Always use FieldType.map(valueType) with an explicit value type.
Avoid raw Map classes in schema-inferred POJOs; use parameterized generics.
Validate schemas in unit tests before running pipelines.

When it happens

Trigger: A FieldType.map(...) was built or deserialized without a value type, or a hand-assembled Schema contains a MAP FieldType whose mapValueType is null. Triggered whenever a Map value is converted via toRow/convertFromBsonValue.

Common situations: Programmatic schema construction mistakes; schemas built via reflection with generics erased (raw Map without type parameters); serialized schemas round-tripped through formats that lose the map value type.

Understand the failure class

Background: Schema validation failed / invalid input schema: payload rejected because its shape doesn't match the expected schema — this error's family across 28 libraries.

Related errors

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

Appendix: source

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

        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);
        }
        for (Map.Entry<?, ?> entry : map.entrySet()) {
          rowMap.put(
              String.valueOf(entry.getKey()), convertFromBsonValue(entry.getValue(), valueType));
        }
        return rowMap;
      case ROW:
        Schema rowSchema = fieldType.getRowSchema();
        if (rowSchema == null) {
          throw new IllegalArgumentException("Row schema cannot be null for type: " + fieldType);
        }
        if (value instanceof Map) {
          return toRow((Map<?, ?>) value, rowSchema);
        } else {
          throw new IllegalArgumentException(
              "Cannot convert value of type "
                  + (value != null ? value.getClass().getName() : "null")

View on GitHub (pinned to 12126d8942)