apache/seatunnel · error · java.lang.IllegalArgumentException

List field must have a child field

Error message

List field must have a child field

What it means

writeListToVector reads the Arrow Field's children to learn the element type of the list; if the Field for a LIST column has no child field, the element type is unknown and the converter throws this IllegalArgumentException. A well-formed Arrow list Field always carries exactly one child, so this indicates a malformed/under-specified schema reaching the converter.

Source

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

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

        UnionListWriter writer = listVector.getWriter();
        writer.setPosition(rowIndex);
        writer.startList();

        java.util.List<?> listValue = (java.util.List<?>) value;
        List<Field> children = field.getChildren();
        if (children.isEmpty()) {
            throw new IllegalArgumentException("List field must have a child field");
        }
        Field elementField = children.get(0);
        ArrowType elementType = elementField.getType();

        for (Object element : listValue) {
            writeListElement(writer, elementType, element, allocator);
        }

        writer.setValueCount(listValue.size());
        writer.endList();
    }

    private static void writeMapToVector(
            MapVector mapVector,
            Field field,
            Object value,
            int rowIndex,
            BufferAllocator allocator) {

View on GitHub (pinned to cf67b549a7)

Solutions

1. Fix the schema construction so the LIST field is created WITH its element child field, e.g. new Field("element", FieldType.nullable(elementType), null).
2. Check the code that converts SeaTunnel ArrayType to Arrow ListType and confirm it propagates the inner element type.
3. Log/print the incoming Arrow schema (Schema.asString()) before writing to spot the empty-children field.
4. If you cannot fix upstream schema generation, add an early validation at job startup that fails fast with the offending field name.

Example fix

// before
new Field("tags", FieldType.nullable(new ArrowType.List()), Collections.emptyList());

// after
Field element = new Field("element", FieldType.nullable(new ArrowType.Utf8()), null);
new Field("tags", FieldType.nullable(new ArrowType.List()), Collections.singletonList(element));

// Java: verify list fields carry an element child before writing
for (Field f : schema.getFields()) {
    if (f.getType() instanceof ArrowType.List && f.getChildren().isEmpty()) {
        throw new IllegalArgumentException("List field '" + f.getName() + "' has no element child");
    }
}

boolean isWellFormedListField(Field f) {
    return !(f.getType() instanceof ArrowType.List) || !f.getChildren().isEmpty();
}

try {
    fragmentConverter.writeListToVector(listVector, field, value, rowIndex, allocator);
} catch (IllegalArgumentException e) {
    if (e.getMessage().equals("List field must have a child field")) {
        throw new IllegalStateException("Malformed Arrow schema: list field '" + field.getName() + "' lacks element type", e);
    }
    throw e;
}

When it happens

Trigger: The Lance sink's target Arrow Schema was built with a LIST field that has empty children — e.g. schema constructed programmatically without registering the element field, or a schema deserialized/converted from SeaTunnel types where the array's inner type was lost.

Common situations: Hand-built Arrow schemas in tests or custom code (new Field("col", FieldType.nullable(new ArrowType.List()), emptyList())); type-conversion bugs where SeaTunnel ArrayType's element type maps to nothing; schema evolution that dropped the element field.

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

• List type should be handled via FragmentConverter.writeListT
• Nested list writing not yet implemented
• Map in list writing not yet implemented
• List type requires List value, got: ${value.getClass()}
• TABLE_DATASET_WRITE_ST_ROW_EXCEPTION

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