apache/cassandra · error · NullPointerException

Map values cannot be null

Error message

Map values cannot be null

What it means

Thrown by MapCodec.serialize() when a map entry has a null value. CQL does not allow null values inside map collections (a null would be indistinguishable from absence/tombstone semantics), so the codec rejects the map at serialization time.

Source

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

                    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");
                }
                try
                {
                    bbv = valueCodec.serialize(v, protocolVersion);
                }
                catch (ClassCastException e)
                {
                    throw new InvalidTypeException(
                    String.format(
                    "Invalid type for map value, expecting %s but got %s",
                    valueCodec.getJavaType(), v.getClass()),
                    e);
                }
                bbs[i++] = bbk;
                bbs[i++] = bbv;
            }
            return CodecUtils.pack(bbs, value.size(), protocolVersion);
        }

View on GitHub (pinned to 88fd0f6a0e)

Solutions

1. Remove null-valued entries before serializing (value.entrySet().removeIf(e -> e.getValue() == null))
2. Skip nulls when building the map instead of putting them
3. Replace nulls with explicit sentinels/default values if absence must be represented

Example fix

// before
m.put("k", null);
codec.serialize(m, version); // NullPointerException
// after
if (v != null) m.put("k", v);
codec.serialize(m, version);

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

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

When it happens

Trigger: Calling MapCodec.serialize() with a Map containing null values, e.g. m.put(k, null), which HashMap permits but CQL map storage does not.

Common situations: Maps populated from JSON/CSV sources where missing fields became nulls; Optional-handling code that inserted null instead of skipping the entry; upstream data with unknown values.

Related errors

• Map keys 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/1ff9a1abac34a389. Report an issue: GitHub.