apache/beam · error · IllegalArgumentException

Row schema cannot be null for type: " + fieldType

Error message

Row schema cannot be null for type: " + fieldType

What it means

convertFromBsonValue hit a ROW FieldType but the FieldType carries no nested Schema (getRowSchema() returned null). Beam ROW types require an embedded Schema describing the nested fields; without it the converter cannot build a Row, so it throws IllegalArgumentException.

Solutions

  1. Build the nested field with Schema.of(Field...) wrapped: FieldType.row(Schema.of(Field.of("name", FieldType.STRING), ...)).
  2. If using inferred schemas, ensure the nested Java class is annotated/registered (DefaultSchema, @SchemaCreate) so its Schema resolves non-null.
  3. Replace the ROW field with MAP if the nested document has dynamic keys and no fixed schema.

Example fix

// before
Field.of("address", FieldType.row(null))
// after
Field.of("address", FieldType.row(Schema.of(Field.of("city", FieldType.STRING))))
Defensive patterns

Strategy: validation

Validate before calling

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

Try / catch

try {
  Row row = toRow(doc, schema);
} catch (IllegalArgumentException e) {
  if (e.getMessage() != null && e.getMessage().contains("Row schema cannot be null")) {
    throw new SchemaConfigurationException("Nested field missing Schema");
  }
  throw e;
}

Prevention

When it happens

Trigger: A nested/struct field was declared as FieldType ROW (e.g. via FieldType.row(null) or an incompletely built schema) and a nested document arrives from MongoDB during toRow/convertFromBsonValue.

Common situations: Hand-built schemas where the nested Schema was forgotten; schemas built via Schema.builder() where the row type was added before its schema existed; schema deserialization that dropped nested schemas.

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/de91e440dca5d1cc. Report an issue: GitHub.

Appendix: source

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

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

View on GitHub (pinned to 12126d8942)