{"record":{"id":"15b9231621d5aefa","repo":"apache/seatunnel","slug":"map-key-cannot-be-null","errorCode":null,"errorMessage":"Map key cannot be null","messagePattern":"Map key cannot be null","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":183,"sourceCode":"\n    private static void writeListElement(\n            UnionListWriter writer,\n            ArrowType elementType,\n            Object element,\n            BufferAllocator allocator) {\n        if (element == null) {\n            writer.writeNull();\n            return;\n        }\n\n        TypeWriter typeWriter = TypeWriterFactory.getWriter(elementType);\n        typeWriter.writeToListWriter(writer, elementType, element, allocator);\n    }\n\n    private static void writeMapKey(\n            UnionMapWriter writer, ArrowType keyType, Object key, BufferAllocator allocator) {\n        if (key == null) {\n            throw new IllegalArgumentException(\"Map key cannot be null\");\n        }\n\n        TypeWriter typeWriter = TypeWriterFactory.getWriter(keyType);\n        typeWriter.writeToMapKey(writer, keyType, key, allocator);\n    }\n\n    private static void writeMapValue(\n            UnionMapWriter writer, ArrowType valueType, Object value, BufferAllocator allocator) {\n        if (value == null) {\n            writer.value().writeNull();\n            return;\n        }\n\n        TypeWriter typeWriter = TypeWriterFactory.getWriter(valueType);\n        typeWriter.writeToMapValue(writer, valueType, value, allocator);\n    }\n}\n","sourceCodeStart":165,"sourceCodeEnd":201,"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#L165-L201","documentation":"Arrow map keys cannot be null by definition. writeMapKey validates each key before writing it via the UnionMapWriter and throws IllegalArgumentException if a key entry is null. Null values are allowed, null keys are not.","triggerScenarios":"A java.util.Map being written contains a null key (e.g. HashMap allows one null key); writeMapToVector iterates entries and calls writeMapKey with key == null.","commonSituations":"Sources deserializing JSON with null object keys into a map; data from systems that permit null keys (HashMap, some NoSQL docs); missing key materialization after upstream joins or lookups.","solutions":["Clean the data upstream: remove or replace null keys before writing (e.g. map to a sentinel or skip)","Convert the map to a TreeMap or filter entries with null keys","If null keys are meaningful, change the column type (e.g. array of structs) instead of MAP","Log the offending row to find the producing source"],"exampleFix":"// before\njava.util.Map<Object,Object> raw = ...; // may contain null key\nconverter.setVectorValue(mapVector, field, raw, i, allocator); // throws\n// after\njava.util.Map<Object,Object> cleaned = new java.util.TreeMap<>();\nraw.forEach((k, v) -> { if (k != null) cleaned.put(k, v); });\nconverter.setVectorValue(mapVector, field, cleaned, i, allocator);","handlingStrategy":"validation","validationCode":"for (java.util.Map.Entry<?,?> e : ((java.util.Map<?,?>) value).entrySet()) {\n    if (e.getKey() == null) {\n        throw new IllegalArgumentException(\"Null map key in column \" + field.getName());\n    }\n}","typeGuard":"boolean hasNoNullKeys(java.util.Map<?,?> m) {\n    return m == null || !m.containsKey(null);\n}","tryCatchPattern":"try {\n    converter.setVectorValue(mapVector, field, value, rowIndex, allocator);\n} catch (IllegalArgumentException e) {\n    if (e.getMessage() != null && e.getMessage().equals(\"Map key cannot be null\")) {\n        LOG.warn(\"Row {} has a null map key in column {}; skipping entry\", rowIndex, field.getName());\n    } else {\n        throw e;\n    }\n}","preventionTips":["Sanitize maps from JSON/NoSQL sources to drop or replace null keys","Prefer structures that reject null keys (TreeMap) at the source","Define a sentinel-value policy instead of null keys","Validate data quality for map columns in CI pipeline tests"],"tags":["arrow","null-key","map","data-quality"],"backgroundTag":"null-argument","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"}