apache/beam · error · IllegalArgumentException

Cannot convert value of type " + (value != null ?…

Error message

Cannot convert value of type " + (value != null ? value.getClass().getName() : "null") + " to Row

What it means

The field is typed ROW and has a valid nested Schema, but the BSON-decoded value is neither null-handled as a Map nor convertible to a Row — it is some other Java class. toRow(Map, Schema) only works for Map-shaped values, so any other runtime type (String, List, ObjectId, etc.) is rejected.

Solutions

Align the Beam schema with the actual stored type: use STRING/OBJECT_ID/ARRAY types for non-document values.
Clean or migrate the MongoDB collection so the field is consistently a sub-document.
Add a transform step that reshapes non-Map values into Maps matching the nested schema before toRow.
Make the schema tolerant: if the field can be either, store it as STRING and parse downstream.

Example fix

// before: field inferred as ROW but data is an array
Field.of("tags", FieldType.row(personSchema))
// after
Field.of("tags", FieldType.array(FieldType.STRING))

Defensive patterns

Strategy: type-guard

Validate before calling

Object v = doc.get(fieldName);
if (v != null && !(v instanceof Map) && schema.getField(fieldName).getType().getTypeName().equals(TypeName.ROW)) {
  throw new IllegalStateException(fieldName + " is not a sub-document: " + v.getClass());
}

Type guard

static boolean isSubDocument(Object v) { return v instanceof java.util.Map; }

Try / catch

try {
  Row row = toRow(doc, schema);
} catch (IllegalArgumentException e) {
  if (e.getMessage() != null && e.getMessage().endsWith(" to Row")) {
    LOG.warn("Skipping doc with non-document struct field: {}", e.getMessage());
    return null;
  }
  throw e;
}

Prevention

Enforce consistent field types with MongoDB schema validation ($jsonSchema) on the collection.
Check a sample of documents across partitions when inferring schemas.
Handle polymorphic fields explicitly with oneOf-like STRING encoding.

When it happens

Trigger: A MongoDB field declared as a nested struct in the Beam schema holds a non-document value (scalar, array, ObjectId, Date) when read; convertFromBsonValue reaches the ROW case with a non-Map object.

Common situations: Documents written with polymorphic/evolving field types (one doc has an object, another a string); schema inference ran on a different document than the one failing; DBRef or ObjectId stored where a sub-document is expected.

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

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

Appendix: source

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

        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")
                  + " to Row");
        }
      default:
        throw new IllegalArgumentException("Unsupported field type: " + fieldType);
    }
  }
}

View on GitHub (pinned to 12126d8942)