apache/iceberg · error · RuntimeException

Field of schema is not a homogenous array. Check option…

Error message

Field ${key} of schema ${builder.name()} is not a homogenous array.
Check option 'struct' of parameter 'array.encoding'

What it means

MongoDataConverter.testType throws RuntimeException when a BSON array contains elements of differing BsonTypes (a non-homogeneous array). The converter with array.encoding=struct requires all array elements to have the same type to derive a single element schema.

Solutions

Make the array homogeneous in MongoDB (all elements the same type).
Switch array.encoding to a non-struct option (e.g. encode arrays as JSON strings).
Clean/normalize existing documents before streaming.

Example fix

// before
db.coll.insertOne({vals: [1, "two"]})
// after
db.coll.insertOne({vals: [1, 2]})

Defensive patterns

Strategy: validation

Validate before calling

// Check array homogeneity before streaming
java.util.Set<BsonType> types = new java.util.HashSet<>();
for (BsonValue el : arrayValue.asArray()) types.add(el.getBsonType());
if (types.size() > 1) throw new IllegalStateException("non-homogeneous array: " + types);

Type guard

boolean isHomogeneous(BsonArray arr) { return arr.stream().map(BsonValue::getBsonType).distinct().count() <= 1; }

Try / catch

try { ... } catch (RuntimeException e) { log.error("Array homogeneity check failed: {}", e.getMessage()); }

Prevention

Enforce consistent array element types at write time in applications
Use array.encoding=json when arrays may be polymorphic
Run a one-off aggregation to find mixed-type arrays before enabling the transform

When it happens

Trigger: addFieldSchema/testType validating an array where elements have mixed BsonTypes, e.g. [1, "two", {"a":1}] processed with array.encoding set to struct.

Common situations: MongoDB documents with polymorphic arrays (mixed scalars/objects), often created by applications with loosely typed writes.

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

Appendix: source

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

  private void testType(SchemaBuilder builder, String key, BsonValue value, BsonType valueType) {
    if (valueType == BsonType.DOCUMENT) {
      final Map<String, BsonType> union = Maps.newHashMap();
      for (BsonValue element : value.asArray()) {
        final BsonDocument arrayDocs = element.asDocument();
        for (Entry<String, BsonValue> arrayDoc : arrayDocs.entrySet()) {
          testArrayElementType(builder, arrayDoc, union);
        }
      }
    } else if (valueType == BsonType.ARRAY) {
      for (BsonValue element : value.asArray()) {
        BsonType subValueType = element.asArray().get(0).getBsonType();
        testType(builder, key, element, subValueType);
      }
    } else {
      for (BsonValue element : value.asArray()) {
        if (element.getBsonType() != valueType) {
          throw new RuntimeException(
              "Field "
                  + key
                  + " of schema "
                  + builder.name()
                  + " is not a homogenous array.\n"
                  + "Check option 'struct' of parameter 'array.encoding'");
        }
      }
    }
  }

  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) {

View on GitHub (pinned to 86d9c8fc54)