{"record":{"id":"2620303f4ff19cbc","repo":"apache/seatunnel","slug":"list-field-must-have-a-child-field","errorCode":null,"errorMessage":"List field must have a child field","messagePattern":"List field must have a child field","errorType":"validation","errorClass":"java.lang.IllegalArgumentException","httpStatus":null,"severity":"error","filePath":"seatunnel-connectors-v2/connector-lance/src/main/java/org/apache/seatunnel/connectors/seatunnel/lance/utils/FragmentConverter.java","lineNumber":119,"sourceCode":"    private static void writeListToVector(\n            ListVector listVector,\n            Field field,\n            Object value,\n            int rowIndex,\n            BufferAllocator allocator) {\n        if (!(value instanceof java.util.List)) {\n            throw new IllegalArgumentException(\n                    \"List type requires List value, got: \" + value.getClass());\n        }\n\n        UnionListWriter writer = listVector.getWriter();\n        writer.setPosition(rowIndex);\n        writer.startList();\n\n        java.util.List<?> listValue = (java.util.List<?>) value;\n        List<Field> children = field.getChildren();\n        if (children.isEmpty()) {\n            throw new IllegalArgumentException(\"List field must have a child field\");\n        }\n        Field elementField = children.get(0);\n        ArrowType elementType = elementField.getType();\n\n        for (Object element : listValue) {\n            writeListElement(writer, elementType, element, allocator);\n        }\n\n        writer.setValueCount(listValue.size());\n        writer.endList();\n    }\n\n    private static void writeMapToVector(\n            MapVector mapVector,\n            Field field,\n            Object value,\n            int rowIndex,\n            BufferAllocator allocator) {","sourceCodeStart":101,"sourceCodeEnd":137,"githubUrl":"https://github.com/apache/seatunnel/blob/cf67b549a7a6c35fa0beb12d83c62892427ea919/seatunnel-connectors-v2/connector-lance/src/main/java/org/apache/seatunnel/connectors/seatunnel/lance/utils/FragmentConverter.java#L101-L137","documentation":"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.","triggerScenarios":"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.","commonSituations":"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.","solutions":["Fix the schema construction so the LIST field is created WITH its element child field, e.g. new Field(\"element\", FieldType.nullable(elementType), null).","Check the code that converts SeaTunnel ArrayType to Arrow ListType and confirm it propagates the inner element type.","Log/print the incoming Arrow schema (Schema.asString()) before writing to spot the empty-children field.","If you cannot fix upstream schema generation, add an early validation at job startup that fails fast with the offending field name."],"exampleFix":"// before\nnew Field(\"tags\", FieldType.nullable(new ArrowType.List()), Collections.emptyList());\n\n// after\nField element = new Field(\"element\", FieldType.nullable(new ArrowType.Utf8()), null);\nnew Field(\"tags\", FieldType.nullable(new ArrowType.List()), Collections.singletonList(element));","handlingStrategy":"validation","validationCode":"// Java: verify list fields carry an element child before writing\nfor (Field f : schema.getFields()) {\n    if (f.getType() instanceof ArrowType.List && f.getChildren().isEmpty()) {\n        throw new IllegalArgumentException(\"List field '\" + f.getName() + \"' has no element child\");\n    }\n}","typeGuard":"boolean isWellFormedListField(Field f) {\n    return !(f.getType() instanceof ArrowType.List) || !f.getChildren().isEmpty();\n}","tryCatchPattern":"try {\n    fragmentConverter.writeListToVector(listVector, field, value, rowIndex, allocator);\n} catch (IllegalArgumentException e) {\n    if (e.getMessage().equals(\"List field must have a child field\")) {\n        throw new IllegalStateException(\"Malformed Arrow schema: list field '\" + field.getName() + \"' lacks element type\", e);\n    }\n    throw e;\n}","preventionTips":["Always construct list Fields with a singletonList element child","Verify the SeaTunnel ArrayType -> Arrow conversion preserves the inner element type","Dump the Arrow schema at startup to catch empty-children list fields early"],"tags":["lance","arrow","schema-validation","list","malformed-schema"],"backgroundTag":"schema-validation-failed","analyzedSha":"cf67b549a7a6c35fa0beb12d83c62892427ea919","analyzedAt":"2026-09-10T21:44:55.265Z","contentChangedAt":"2026-09-10T21:44:55.265Z","schemaVersion":2},"datasetVersion":"2026-09-14T11:17:12.474Z"}