{"record":{"id":"d55402afa35639ae","repo":"apache/flink","slug":"parquet-does-not-support-null-keys-in-maps-see-ht","errorCode":null,"errorMessage":"Parquet does not support null keys in maps. See https://github.com/apache/parquet-format/blob/master/LogicalTypes.md#maps for more details.","messagePattern":"Parquet does not support null keys in maps\\. See https://github\\.com/apache/parquet-format/blob/master/LogicalTypes\\.md#maps for more details\\.","errorType":"validation","errorClass":"IllegalArgumentException","httpStatus":null,"severity":"error","filePath":"flink-formats/flink-parquet/src/main/java/org/apache/flink/formats/parquet/row/ParquetRowDataWriter.java","lineNumber":408,"sourceCode":"        }\n\n        private void writeMapData(MapData mapData) {\n            recordConsumer.startGroup();\n\n            if (mapData != null && mapData.size() > 0) {\n                recordConsumer.startField(repeatedGroupName, 0);\n\n                ArrayData keyArray = mapData.keyArray();\n                ArrayData valueArray = mapData.valueArray();\n                for (int i = 0; i < keyArray.size(); i++) {\n                    recordConsumer.startGroup();\n                    if (!keyArray.isNullAt(i)) {\n                        // write key element\n                        recordConsumer.startField(keyName, 0);\n                        keyWriter.write(keyArray, i);\n                        recordConsumer.endField(keyName, 0);\n                    } else {\n                        throw new IllegalArgumentException(\n                                \"Parquet does not support null keys in maps. See https://github.com/apache/parquet-format/blob/master/LogicalTypes.md#maps for more details.\");\n                    }\n\n                    if (!valueArray.isNullAt(i)) {\n                        // write value element\n                        recordConsumer.startField(valueName, 1);\n                        valueWriter.write(valueArray, i);\n                        recordConsumer.endField(valueName, 1);\n                    }\n                    recordConsumer.endGroup();\n                }\n\n                recordConsumer.endField(repeatedGroupName, 0);\n            }\n            recordConsumer.endGroup();\n        }\n    }\n","sourceCodeStart":390,"sourceCodeEnd":426,"githubUrl":"https://github.com/apache/flink/blob/2f3c205e9266cb30240eb7f4fdab15cad629a70f/flink-formats/flink-parquet/src/main/java/org/apache/flink/formats/parquet/row/ParquetRowDataWriter.java#L390-L426","documentation":"The parquet map logical type requires keys to be non-null. When writing a Flink MAP column, if any key element is null, ParquetRowDataWriter throws IllegalArgumentException referencing the parquet LogicalTypes spec, because a null key cannot be represented in the MAP key_value encoding.","triggerScenarios":"Writing RowData where mapData.keyArray().isNullAt(i) is true for any entry - i.e. the input map contains a null key.","commonSituations":"Upstream data (Kafka JSON, JDBC, user functions) producing maps with null keys; Java HashMap允许 null keys flowing into a map-typed column; missing null-key filtering before the parquet sink.","solutions":["Filter out or replace null keys before the sink: map entries with null keys are dropped or given a sentinel key","Fix the producer so null keys never enter the map column","If null keys are semantically required, model the data as an ARRAY<ROW<key,value>> instead of MAP"],"exampleFix":"// before\nMap<String,Integer> in = new HashMap<>();\nin.put(null, 1); // null key -> throws at parquet write\n\n// after\nin.entrySet().removeIf(e -> e.getKey() == null);\n// or use ARRAY<ROW<k STRING, v INT>> to permit null keys","handlingStrategy":"validation","validationCode":"static boolean hasNullKeys(MapData m) {\n  ArrayData keys = m.keyArray();\n  for (int i = 0; i < keys.size(); i++) { if (keys.isNullAt(i)) return true; }\n  return false;\n}","typeGuard":null,"tryCatchPattern":"try { writer.write(row); } catch (IllegalArgumentException e) { if (e.getMessage().contains(\"null keys in maps\")) { /* sanitize map and re-emit */ } throw e; }","preventionTips":["Sanitize maps upstream: drop or remap null-key entries before the parquet sink","Avoid Java maps with null keys (HashMap allows them) feeding map-typed columns","If null keys are meaningful, model as ARRAY<ROW<key,value>> instead of MAP"],"tags":["parquet","map","null-key","data-quality"],"backgroundTag":null,"analyzedSha":"2f3c205e9266cb30240eb7f4fdab15cad629a70f","analyzedAt":"2026-08-14T08:48:24.518Z","schemaVersion":2},"datasetVersion":"2026-08-14T10:17:34.591Z"}