{"record":{"id":"95b6e20bb6b8c6da","repo":"apache/seatunnel","slug":"map-field-must-have-key-and-value-child-fields","errorCode":null,"errorMessage":"Map field must have key and value child fields","messagePattern":"Map field must have key and value child fields","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":150,"sourceCode":"    private static void writeMapToVector(\n            MapVector mapVector,\n            Field field,\n            Object value,\n            int rowIndex,\n            BufferAllocator allocator) {\n        if (!(value instanceof java.util.Map)) {\n            throw new IllegalArgumentException(\n                    \"Map type requires Map value, got: \" + value.getClass());\n        }\n\n        UnionMapWriter writer = mapVector.getWriter();\n        writer.setPosition(rowIndex);\n        writer.startMap();\n\n        java.util.Map<?, ?> mapValue = (java.util.Map<?, ?>) value;\n        List<Field> children = field.getChildren();\n        if (children.size() < 2) {\n            throw new IllegalArgumentException(\"Map field must have key and value child fields\");\n        }\n        Field keyField = children.get(0);\n        Field valueField = children.get(1);\n        ArrowType keyType = keyField.getType();\n        ArrowType valueType = valueField.getType();\n\n        for (java.util.Map.Entry<?, ?> entry : mapValue.entrySet()) {\n            writer.startEntry();\n            writeMapKey(writer, keyType, entry.getKey(), allocator);\n            writeMapValue(writer, valueType, entry.getValue(), allocator);\n            writer.endEntry();\n        }\n        writer.endMap();\n    }\n\n    private static void writeListElement(\n            UnionListWriter writer,\n            ArrowType elementType,","sourceCodeStart":132,"sourceCodeEnd":168,"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#L132-L168","documentation":"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.","triggerScenarios":"writeMapToVector receives a Field whose getChildren().size() < 2 after calling writer.startMap(), i.e. the map Field was constructed without key/value child fields.","commonSituations":"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.","solutions":["Rebuild the Arrow map Field with exactly two child fields (key, value)","Check the SeaTunnel-to-Arrow type conversion that produced the Field","Verify the Lance table schema matches the expected map structure","Log the field's children to confirm which child fields are missing"],"exampleFix":"// before\nField mapField = new Field(\"m\", FieldType.nullable(new ArrowType.Map(false)),\n        java.util.Collections.emptyList()); // no children\n// after\nField keyField = new Field(\"keys\", FieldType.nullable(new ArrowType.Utf8()), null);\nField valField = new Field(\"values\", FieldType.nullable(new ArrowType.Int(32, true)), null);\nField mapField = new Field(\"m\", FieldType.nullable(new ArrowType.Map(false)),\n        java.util.Arrays.asList(\n            new Field(\"entries\", FieldType.notNullable(new ArrowType.Struct()),\n                java.util.Arrays.asList(keyField, valField))));","handlingStrategy":"validation","validationCode":"List<Field> children = field.getChildren();\nif (children.size() < 2) {\n    throw new IllegalArgumentException(\"Field '\" + field.getName()\n        + \"' is not a valid Arrow map: needs key and value children, found \" + children.size());\n}","typeGuard":"boolean isValidArrowMapField(Field f) {\n    return f.getType() instanceof ArrowType.Map && f.getChildren().size() >= 2;\n}","tryCatchPattern":"try {\n    converter.setVectorValue(mapVector, field, value, rowIndex, allocator);\n} catch (IllegalArgumentException e) {\n    if (e.getMessage() != null && e.getMessage().contains(\"key and value child fields\")) {\n        throw new IllegalStateException(\"Malformed Arrow map schema for field \" + field.getName(), e);\n    }\n    throw e;\n}","preventionTips":["Always build Arrow map fields through a tested SeaTunnel-to-Arrow type converter","Unit-test schema construction so every MAP type yields key+value children","Validate the Arrow schema once at job start, not per row","Avoid hand-constructed Field objects for map types"],"tags":["arrow","map-schema","schema","lance"],"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"}