{"record":{"id":"ebc125cd65d3f596","repo":"apache/cassandra","slug":"map-keys-cannot-be-null","errorCode":null,"errorMessage":"Map keys cannot be null","messagePattern":"Map keys cannot be null","errorType":"exception","errorClass":"NullPointerException","httpStatus":null,"severity":"error","filePath":"src/java/org/apache/cassandra/cql3/functions/types/TypeCodec.java","lineNumber":2457,"sourceCode":"                sb.append(valueCodec.format(e.getValue()));\n            }\n            sb.append('}');\n            return sb.toString();\n        }\n\n        @Override\n        public ByteBuffer serialize(Map<K, V> value, ProtocolVersion protocolVersion)\n        {\n            if (value == null) return null;\n            int i = 0;\n            ByteBuffer[] bbs = new ByteBuffer[2 * value.size()];\n            for (Map.Entry<K, V> entry : value.entrySet())\n            {\n                ByteBuffer bbk;\n                K key = entry.getKey();\n                if (key == null)\n                {\n                    throw new NullPointerException(\"Map keys cannot be null\");\n                }\n                try\n                {\n                    bbk = keyCodec.serialize(key, protocolVersion);\n                }\n                catch (ClassCastException e)\n                {\n                    throw new InvalidTypeException(\n                    String.format(\n                    \"Invalid type for map key, expecting %s but got %s\",\n                    keyCodec.getJavaType(), key.getClass()),\n                    e);\n                }\n                ByteBuffer bbv;\n                V v = entry.getValue();\n                if (v == null)\n                {\n                    throw new NullPointerException(\"Map values cannot be null\");","sourceCodeStart":2439,"sourceCodeEnd":2475,"githubUrl":"https://github.com/apache/cassandra/blob/88fd0f6a0eaed8943f05ac9e8f947882b8ddc8f1/src/java/org/apache/cassandra/cql3/functions/types/TypeCodec.java#L2439-L2475","documentation":"Thrown by MapCodec.serialize() when a map entry has a null key. CQL map keys are part of the primary-value encoding and cannot be null, so the codec refuses to serialize such a map rather than produce an invalid protocol buffer.","triggerScenarios":"Calling MapCodec.serialize() (directly or via a bound statement / format path) with a Map that contains a null key, e.g. HashMap permitting put(null, v).","commonSituations":"Java maps built with null keys (HashMap allows it); deserialized JSON objects where a missing name became a null key; upstream data with sentinel null keys that was never cleaned.","solutions":["Remove or replace null keys in the Map before serializing","Use a map implementation that rejects null keys (e.g. TreeMap) to fail fast at insert time","Filter entries: value.entrySet().removeIf(e -> e.getKey() == null)"],"exampleFix":"// before\nMap<Integer,String> m = new HashMap<>();\nm.put(null, \"x\");\ncodec.serialize(m, version); // NullPointerException\n// after\nm.remove(null);\ncodec.serialize(m, version);","handlingStrategy":"validation","validationCode":"if (map.keySet().stream().anyMatch(Objects::isNull))\n    throw new IllegalArgumentException(\"Map contains null keys\");\ncodec.serialize(map, protocolVersion);","typeGuard":null,"tryCatchPattern":"try {\n    codec.serialize(map, protocolVersion);\n} catch (NullPointerException e) {\n    if (e.getMessage() != null && e.getMessage().contains(\"Map keys cannot be null\")) {\n        map.entrySet().removeIf(en -> en.getKey() == null);\n        return codec.serialize(map, protocolVersion);\n    }\n    throw e;\n}","preventionTips":["Never call put(null, v) on maps destined for CQL","Use TreeMap or other null-hostile map implementations","Sanitize deserialized JSON before binding"],"tags":["map","null","serialization","codec"],"backgroundTag":"null-argument","analyzedSha":"88fd0f6a0eaed8943f05ac9e8f947882b8ddc8f1","analyzedAt":"2026-09-10T07:29:22.284Z","contentChangedAt":"2026-09-10T07:29:22.284Z","schemaVersion":2},"datasetVersion":"2026-09-14T16:17:12.679Z"}