apache/seatunnel · error · java.lang.IllegalArgumentException

List type requires List value, got: ${value.getClass()}

Error message

List type requires List value, got: ${value.getClass()}

What it means

FragmentConverter.writeListToVector requires the Java value behind an Arrow LIST column to be a java.util.List. When the Lance sink's row value for a list-typed column is any other object (array primitive, string, map, etc.), the cast guard throws this IllegalArgumentException with the actual runtime class.

Source

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

        if (arrowType instanceof ArrowType.List) {
            writeListToVector((ListVector) vector, field, value, rowIndex, allocator);
        } else if (arrowType instanceof ArrowType.Map) {
            writeMapToVector((MapVector) vector, field, value, rowIndex, allocator);
        } else {
            TypeWriter writer = TypeWriterFactory.getWriter(arrowType);
            writer.writeToVector(vector, arrowType, value, rowIndex, allocator);
        }
    }

    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);
        }

View on GitHub (pinned to cf67b549a7)

Solutions

1. Wrap the value in a java.util.List (e.g. Arrays.asList(...) for Object[]) before writing the row.
2. If the value is a JSON string, parse it into a List first rather than passing the raw string.
3. Verify the SeaTunnel column type matches the actual value type produced by your source/transform.
4. Use Arrays.asList(java.util.Arrays.stream(arr).boxed().toArray()) conversion helpers if the producer only has primitive arrays.

Example fix

// before
row.setField(2, "{\"a\":1}");  // string for array column

// after
row.setField(2, java.util.Arrays.asList("a", "b"));

// Java: ensure the value is a List before writing
if (!(value instanceof java.util.List)) {
    throw new IllegalArgumentException("Array column requires java.util.List value");
}

boolean isListValue(Object v) {
    return v instanceof java.util.List;
}

Object normalize(Object v) {
    if (v instanceof Object[]) return java.util.Arrays.asList((Object[]) v);
    return v;
}

try {
    fragmentConverter.writeListToVector(listVector, field, value, rowIndex, allocator);
} catch (IllegalArgumentException e) {
    if (e.getMessage().contains("List type requires List value")) {
        throw new IllegalStateException("Producer must emit java.util.List for array column '" + field.getName() + "'", e);
    }
    throw e;
}

When it happens

Trigger: SeaTunnel Row field for a column declared ARRAY carries a non-List object — e.g. a String containing JSON, a Scala/other collection type, or a single element not wrapped in a list — and setVectorValue dispatches it to writeListToVector.

Common situations: Custom transforms/sources that set the field to a raw JSON string for an array column; type drift after schema changes (column re-typed to array but data pipeline not updated); passing Java arrays (Object[]) instead of List.

Understand the failure class

Background: Type mismatch errors: IllegalArgumentException, TypeError and type guards across 150 open-source libraries — this error's family across 150 libraries.

Related errors

• Unsupported timestamp value type:
• Unsupported date value type:
• List type should be handled via FragmentConverter.writeListT
• Nested list writing not yet implemented
• Map in list writing not yet implemented

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