apache/iceberg · error · RuntimeException

Field of schema is not the same type for all documents in…

Error message

Field ${docKey} of schema ${builder.name()} is not the same type for all documents in the array.
Check option 'struct' of parameter 'array.encoding'

What it means

MongoDataConverter.testArrayElementType throws RuntimeException when, across documents in an array-of-documents (array.encoding=struct), a given key has differing BSON types between documents (ignoring NULL vs value unions). All documents in the array must agree on each field's type.

Solutions

Normalize the field's type across all array elements in MongoDB (e.g. cast via aggregation pipeline update).
Use a non-struct array.encoding so arrays are passed as JSON instead of inferred struct schemas.
Fix the writing application to use a consistent schema.

Example fix

// before
db.coll.insertMany([{items:[{amt:1}]},{items:[{amt:"2"}]}])
// after
db.coll.insertMany([{items:[{amt:1}]},{items:[{amt:2}]}])

Defensive patterns

Strategy: validation

Validate before calling

// Verify each key has one non-null type across array documents
java.util.Map<String, BsonType> seen = new java.util.HashMap<>();
for (BsonValue el : arr.asArray()) {
  BsonDocument d = el.asDocument();
  for (var e : d.entrySet()) {
    BsonType t = e.getValue().isNull() ? BsonType.NULL : e.getValue().getBsonType();
    BsonType prev = seen.putIfAbsent(e.getKey(), t);
    if (prev != null && !prev.equals(t) && prev != BsonType.NULL && t != BsonType.NULL) throw new IllegalStateException("type conflict for " + e.getKey());
  }
}

Try / catch

try { ... } catch (RuntimeException e) { log.error("Inconsistent array document types: {}", e.getMessage()); }

Prevention

Normalize field types across documents in arrays (e.g. always numeric amounts)
Use MongoDB $type validation rules per array element
Prefer array.encoding=json for legacy collections

When it happens

Trigger: subSchema/testType processing an array of documents where docKey has type STRING in one document and INT (or another non-null-differing type) in another.

Common situations: MongoDB arrays of objects where the same field is stored with inconsistent types across elements — e.g. amounts sometimes as number, sometimes as string; legacy documents mixed with new ones.

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/iceberg@86d9c8fc54 (2026-09-12). Data as JSON: /api/errors/18bbd3ae8884e402. Report an issue: GitHub.

Appendix: source

Thrown at kafka-connect/kafka-connect-transforms/src/main/java/org/debezium/connector/mongodb/transforms/MongoDataConverter.java:506

      }
    }
  }

  private void testArrayElementType(
      SchemaBuilder builder, Entry<String, BsonValue> arrayDoc, Map<String, BsonType> union) {
    final String docKey = (String) arrayDoc.getKey();
    final BsonType currentType = arrayDoc.getValue().getBsonType();
    final BsonType prevType = union.putIfAbsent(docKey, currentType);

    if (prevType != null) {
      if ((prevType == BsonType.NULL || currentType == BsonType.NULL)
          && !Objects.equals(prevType, currentType)) {
        // set non-null type as real schema
        if (prevType == BsonType.NULL) {
          union.put(docKey, currentType);
        }
      } else if (!Objects.equals(prevType, currentType)) {
        throw new RuntimeException(
            "Field "
                + docKey
                + " of schema "
                + builder.name()
                + " is not the same type for all documents in the array.\n"
                + "Check option 'struct' of parameter 'array.encoding'");
      }
    }
  }
}

View on GitHub (pinned to 86d9c8fc54)