apache/beam · error · IllegalArgumentException

Expected Document but got " + (converted != null ? converted

Error message

Expected Document but got " + (converted != null ? converted.getClass().getName() : "null")

What it means

MongoDbUtils.toDocument converts a Beam Row to a BSON Document by calling convertToBsonValue on the whole row; the result must be a Document. If conversion produces anything else (or null), the method throws this IllegalArgumentException, indicating the Row's shape did not convert as expected.

Source

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

import org.apache.beam.sdk.schemas.Schema.Field;
import org.apache.beam.sdk.schemas.Schema.FieldType;
import org.apache.beam.sdk.values.Row;
import org.bson.BsonNull;
import org.bson.Document;
import org.bson.types.Binary;
import org.checkerframework.checker.nullness.qual.Nullable;
import org.joda.time.Instant;

/** Utility methods for MongoDB IO. */
public class MongoDbUtils {

  /** Converts a Beam {@link Row} to a BSON {@link Document}. */
  public static Document toDocument(Row row) {
    Object converted = convertToBsonValue(row);
    if (converted instanceof Document) {
      return (Document) converted;
    }
    throw new IllegalArgumentException(
        "Expected Document but got "
            + (converted != null ? converted.getClass().getName() : "null"));
  }

  private static @Nullable Object convertToBsonValue(@Nullable Object value) {
    if (value == null) {
      return new BsonNull();
    }
    if (value instanceof Row) {
      Row row = (Row) value;
      Document doc = new Document();
      for (Field field : row.getSchema().getFields()) {
        Object fieldValue = row.getValue(field.getName());
        Object converted = convertToBsonValue(fieldValue);
        doc.append(field.getName(), converted != null ? converted : new BsonNull());
      }
      return doc;
    } else if (value instanceof Iterable) {

View on GitHub (pinned to 12126d8942)

Solutions

  1. Ensure the Row has the schema/layout expected for a MongoDB document (row-to-document conversion path), matching field types to BSON-compatible values
  2. Check for null or malformed input Rows before calling toDocument
  3. Convert field values to BSON-supported types; wrap the call and handle IllegalArgumentException to log/dump the offending Row

Example fix

// before
Document doc = MongoDbUtils.toDocument(null); // throws
// after
if (row == null || row.getFieldCount() == 0) {
  throw new IllegalArgumentException("Refusing empty row");
}
Document doc = MongoDbUtils.toDocument(row);
Defensive patterns

Strategy: type-guard

Validate before calling

if (row == null || row.getFieldCount() == 0) {
  throw new IllegalArgumentException("toDocument requires a non-empty Row");
}

Type guard

static boolean isDocumentConvertible(@Nullable Row row) {
  return row != null && row.getFieldCount() > 0;
}

Try / catch

try {
  Document doc = MongoDbUtils.toDocument(row);
} catch (IllegalArgumentException e) {
  if (e.getMessage().startsWith("Expected Document but got")) {
    // log row schema/values and fix conversion input
  }
}

Prevention

When it happens

Trigger: Calling MongoDbUtils.toDocument(row) with a Row whose converted form is not a Document — e.g., a Row that maps to a plain map/primitive, or a null/empty row producing null.

Common situations: Writing Beam Rows to MongoDB where the Row layout doesn't match what the BSON converter expects (nested/flat mismatch, wrong schema), or passing a null/invalid Row programmatically.

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