apache/seatunnel · error · java.lang.IllegalArgumentException

Map field must have key and value child fields

Error message

Map field must have key and value child fields

What it means

Arrow MapVector fields must contain (at least) two child fields: a key field and a value field. FragmentConverter throws this when the Field backing the map vector has fewer than 2 children, meaning the Arrow schema for the map is malformed or was built incorrectly.

Source

Thrown at seatunnel-connectors-v2/connector-lance/src/main/java/org/apache/seatunnel/connectors/seatunnel/lance/utils/FragmentConverter.java:150

    private static void writeMapToVector(
            MapVector mapVector,
            Field field,
            Object value,
            int rowIndex,
            BufferAllocator allocator) {
        if (!(value instanceof java.util.Map)) {
            throw new IllegalArgumentException(
                    "Map type requires Map value, got: " + value.getClass());
        }

        UnionMapWriter writer = mapVector.getWriter();
        writer.setPosition(rowIndex);
        writer.startMap();

        java.util.Map<?, ?> mapValue = (java.util.Map<?, ?>) value;
        List<Field> children = field.getChildren();
        if (children.size() < 2) {
            throw new IllegalArgumentException("Map field must have key and value child fields");
        }
        Field keyField = children.get(0);
        Field valueField = children.get(1);
        ArrowType keyType = keyField.getType();
        ArrowType valueType = valueField.getType();

        for (java.util.Map.Entry<?, ?> entry : mapValue.entrySet()) {
            writer.startEntry();
            writeMapKey(writer, keyType, entry.getKey(), allocator);
            writeMapValue(writer, valueType, entry.getValue(), allocator);
            writer.endEntry();
        }
        writer.endMap();
    }

    private static void writeListElement(
            UnionListWriter writer,
            ArrowType elementType,

View on GitHub (pinned to cf67b549a7)

Solutions

1. Rebuild the Arrow map Field with exactly two child fields (key, value)
2. Check the SeaTunnel-to-Arrow type conversion that produced the Field
3. Verify the Lance table schema matches the expected map structure
4. Log the field's children to confirm which child fields are missing

Example fix

// before
Field mapField = new Field("m", FieldType.nullable(new ArrowType.Map(false)),
        java.util.Collections.emptyList()); // no children
// after
Field keyField = new Field("keys", FieldType.nullable(new ArrowType.Utf8()), null);
Field valField = new Field("values", FieldType.nullable(new ArrowType.Int(32, true)), null);
Field mapField = new Field("m", FieldType.nullable(new ArrowType.Map(false)),
        java.util.Arrays.asList(
            new Field("entries", FieldType.notNullable(new ArrowType.Struct()),
                java.util.Arrays.asList(keyField, valField))));

List<Field> children = field.getChildren();
if (children.size() < 2) {
    throw new IllegalArgumentException("Field '" + field.getName()
        + "' is not a valid Arrow map: needs key and value children, found " + children.size());
}

boolean isValidArrowMapField(Field f) {
    return f.getType() instanceof ArrowType.Map && f.getChildren().size() >= 2;
}

try {
    converter.setVectorValue(mapVector, field, value, rowIndex, allocator);
} catch (IllegalArgumentException e) {
    if (e.getMessage() != null && e.getMessage().contains("key and value child fields")) {
        throw new IllegalStateException("Malformed Arrow map schema for field " + field.getName(), e);
    }
    throw e;
}

When it happens

Trigger: writeMapToVector receives a Field whose getChildren().size() < 2 after calling writer.startMap(), i.e. the map Field was constructed without key/value child fields.

Common situations: Programmatically built Arrow schemas missing children; schema translation from SeaTunnel types to Arrow dropped children; corrupted or hand-edited schema definitions; version mismatch between schema-producing and schema-consuming code.

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

• TABLE_DATASET_WRITE_ST_ROW_EXCEPTION
• Unknown Arrow type: {}, defaulting to utf8
• Unknown JsonArrow type: {}, defaulting to utf8
• seaTunnelDataType cannot be null
• Unsupported timestamp value type:

AI-assisted analysis of apache/seatunnel@cf67b549a7 (2026-09-10). Data as JSON: /api/errors/95b6e20bb6b8c6da. Report an issue: GitHub.