{"record":{"id":"b00e5c45d977c713","repo":"apache/beam","slug":"expected-document-but-got-converted-null-converted-getclass","errorCode":null,"errorMessage":"Expected Document but got \" + (converted != null ? converted.getClass().getName() : \"null\")","messagePattern":"Expected Document but got \" \\+ \\(converted != null \\? converted\\.getClass\\(\\)\\.getName\\(\\) : \"null\"\\)","errorType":"validation","errorClass":"IllegalArgumentException","httpStatus":null,"severity":"error","filePath":"sdks/java/io/mongodb/src/main/java/org/apache/beam/sdk/io/mongodb/MongoDbUtils.java","lineNumber":43,"sourceCode":"import org.apache.beam.sdk.schemas.Schema.Field;\nimport org.apache.beam.sdk.schemas.Schema.FieldType;\nimport org.apache.beam.sdk.values.Row;\nimport org.bson.BsonNull;\nimport org.bson.Document;\nimport org.bson.types.Binary;\nimport org.checkerframework.checker.nullness.qual.Nullable;\nimport org.joda.time.Instant;\n\n/** Utility methods for MongoDB IO. */\npublic class MongoDbUtils {\n\n  /** Converts a Beam {@link Row} to a BSON {@link Document}. */\n  public static Document toDocument(Row row) {\n    Object converted = convertToBsonValue(row);\n    if (converted instanceof Document) {\n      return (Document) converted;\n    }\n    throw new IllegalArgumentException(\n        \"Expected Document but got \"\n            + (converted != null ? converted.getClass().getName() : \"null\"));\n  }\n\n  private static @Nullable Object convertToBsonValue(@Nullable Object value) {\n    if (value == null) {\n      return new BsonNull();\n    }\n    if (value instanceof Row) {\n      Row row = (Row) value;\n      Document doc = new Document();\n      for (Field field : row.getSchema().getFields()) {\n        Object fieldValue = row.getValue(field.getName());\n        Object converted = convertToBsonValue(fieldValue);\n        doc.append(field.getName(), converted != null ? converted : new BsonNull());\n      }\n      return doc;\n    } else if (value instanceof Iterable) {","sourceCodeStart":25,"sourceCodeEnd":61,"githubUrl":"https://github.com/apache/beam/blob/12126d8942aaf848030c478b4c6a28c6af861c66/sdks/java/io/mongodb/src/main/java/org/apache/beam/sdk/io/mongodb/MongoDbUtils.java#L25-L61","documentation":"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.","triggerScenarios":"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.","commonSituations":"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.","solutions":["Ensure the Row has the schema/layout expected for a MongoDB document (row-to-document conversion path), matching field types to BSON-compatible values","Check for null or malformed input Rows before calling toDocument","Convert field values to BSON-supported types; wrap the call and handle IllegalArgumentException to log/dump the offending Row"],"exampleFix":"// before\nDocument doc = MongoDbUtils.toDocument(null); // throws\n// after\nif (row == null || row.getFieldCount() == 0) {\n  throw new IllegalArgumentException(\"Refusing empty row\");\n}\nDocument doc = MongoDbUtils.toDocument(row);","handlingStrategy":"type-guard","validationCode":"if (row == null || row.getFieldCount() == 0) {\n  throw new IllegalArgumentException(\"toDocument requires a non-empty Row\");\n}","typeGuard":"static boolean isDocumentConvertible(@Nullable Row row) {\n  return row != null && row.getFieldCount() > 0;\n}","tryCatchPattern":"try {\n  Document doc = MongoDbUtils.toDocument(row);\n} catch (IllegalArgumentException e) {\n  if (e.getMessage().startsWith(\"Expected Document but got\")) {\n    // log row schema/values and fix conversion input\n  }\n}","preventionTips":["Only pass Rows built with a document-shaped schema to toDocument","Guard against null/empty Rows before conversion","Write round-trip tests (Row -> Document -> Row) for your schemas"],"tags":["java","apache-beam","mongodb","row-conversion","type-mismatch"],"backgroundTag":"type-mismatch","analyzedSha":"12126d8942aaf848030c478b4c6a28c6af861c66","analyzedAt":"2026-09-13T01:50:10.254Z","contentChangedAt":"2026-09-13T01:50:10.254Z","schemaVersion":2},"datasetVersion":"2026-09-14T16:17:12.679Z"}