apache/cassandra · error · NullPointerException

Map keys cannot be null

Error message

Map keys cannot be null

What it means

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.

Source

Thrown at src/java/org/apache/cassandra/cql3/functions/types/TypeCodec.java:2457

                sb.append(valueCodec.format(e.getValue()));
            }
            sb.append('}');
            return sb.toString();
        }

        @Override
        public ByteBuffer serialize(Map<K, V> value, ProtocolVersion protocolVersion)
        {
            if (value == null) return null;
            int i = 0;
            ByteBuffer[] bbs = new ByteBuffer[2 * value.size()];
            for (Map.Entry<K, V> entry : value.entrySet())
            {
                ByteBuffer bbk;
                K key = entry.getKey();
                if (key == null)
                {
                    throw new NullPointerException("Map keys cannot be null");
                }
                try
                {
                    bbk = keyCodec.serialize(key, protocolVersion);
                }
                catch (ClassCastException e)
                {
                    throw new InvalidTypeException(
                    String.format(
                    "Invalid type for map key, expecting %s but got %s",
                    keyCodec.getJavaType(), key.getClass()),
                    e);
                }
                ByteBuffer bbv;
                V v = entry.getValue();
                if (v == null)
                {
                    throw new NullPointerException("Map values cannot be null");

View on GitHub (pinned to 88fd0f6a0e)

Solutions

1. Remove or replace null keys in the Map before serializing
2. Use a map implementation that rejects null keys (e.g. TreeMap) to fail fast at insert time
3. Filter entries: value.entrySet().removeIf(e -> e.getKey() == null)

Example fix

// before
Map<Integer,String> m = new HashMap<>();
m.put(null, "x");
codec.serialize(m, version); // NullPointerException
// after
m.remove(null);
codec.serialize(m, version);

if (map.keySet().stream().anyMatch(Objects::isNull))
    throw new IllegalArgumentException("Map contains null keys");
codec.serialize(map, protocolVersion);

try {
    codec.serialize(map, protocolVersion);
} catch (NullPointerException e) {
    if (e.getMessage() != null && e.getMessage().contains("Map keys cannot be null")) {
        map.entrySet().removeIf(en -> en.getKey() == null);
        return codec.serialize(map, protocolVersion);
    }
    throw e;
}

When it happens

Trigger: 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).

Common situations: 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.

Related errors

• Map values cannot be null
• Invalid type for map key, expecting %s but got %s
• null is not supported inside collections
• Invalid 32-bits integer value, expecting 4 bytes but got %d
• cannot parse map value from "%s", at character %d expecting

AI-assisted analysis of apache/cassandra@88fd0f6a0e (2026-09-10). Data as JSON: /api/errors/ebc125cd65d3f596. Report an issue: GitHub.