apache/cassandra · error · InvalidRequestException

Invalid null map key

Error message

Invalid null map key

What it means

Fired when executing a SET map[key] = ... operation on a non-frozen (multi-cell) map: the bound key term evaluated to null (e.g. 'SET m[null] = 1' or a bound variable left null). Null is not a valid map key, so the update is rejected with an InvalidRequestException before building the cell.

Solutions

1. Bind a non-null key value before executing.
2. Skip the statement or use a whole-map update when the key is absent.
3. Validate keys client-side and reject nulls early.

Example fix

// before
session.execute("UPDATE t SET m[?] = ? WHERE k=?", null, val, pk);
// after
if (mapKey != null)
    session.execute("UPDATE t SET m[?] = ? WHERE k=?", mapKey, val, pk);

if (mapKey == null) throw new IllegalArgumentException("map key must not be null");

boolean validMapKey(Object k) { return k != null && !(k instanceof ByteBuffer && k == ByteBufferUtil.UNSET_BYTE_BUFFER); }

try { session.execute("UPDATE t SET m[?] = ? WHERE k=?", mapKey, val, pk); } catch (InvalidRequestException e) { if (e.getMessage().contains("Invalid null map key")) { /* fix binding */ } else throw e; }

When it happens

Trigger: Executing `UPDATE t SET m[?] = ? WHERE ...` where the key bind parameter is bound to null.

Common situations: Optional key fields in application code left null; ORM mapping null map keys; drivers deserializing missing key columns as null.

Related errors

• Invalid unset map key
• A TTL must be greater or equal to 0, but was
• Attempted to delete an element from a list which is null
• Cannot create ENTRIES index on frozen map clustering column
• Cannot create index on

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

Appendix: source

Thrown at src/java/org/apache/cassandra/cql3/terms/Maps.java:291

        {
            super(column, t);
            this.k = k;
        }

        @Override
        public void collectMarkerSpecification(VariableSpecifications boundNames, Object owner)
        {
            super.collectMarkerSpecification(boundNames, owner);
            k.collectMarkerSpecification(boundNames, owner);
        }

        public void execute(DecoratedKey partitionKey, RowUpdateBuilder builder) throws InvalidRequestException
        {
            assert column.type.isMultiCell() : "Attempted to set a value for a single key on a frozen map";
            ByteBuffer key = k.bindAndGet(builder);
            ByteBuffer value = t.bindAndGet(builder);
            if (key == null)
                throw new InvalidRequestException("Invalid null map key");
            if (key == ByteBufferUtil.UNSET_BYTE_BUFFER)
                throw new InvalidRequestException("Invalid unset map key");

            CellPath path = CellPath.create(key);

            if (value == null)
            {
                builder.addTombstone(column, path);
            }
            else if (value != ByteBufferUtil.UNSET_BYTE_BUFFER)
            {
                builder.addCell(column, path, value);
            }
        }
    }

    public static class Putter extends Operation
    {

View on GitHub (pinned to 88fd0f6a0e)