apache/cassandra · error · InvalidRequestException

Invalid map literal for %s: key %s is not of type %s

Error message

Invalid map literal for %s: key %s is not of type %s

What it means

Fired by Maps literal preparation when a map literal key element's type is not assignable to the declared key type of the target map column. It is a CQL statement validation guard: the map literal itself parses, but the key expression (e.g. an int literal in a text-keyed map) fails AssignmentTestable.TestResult.NOT_ASSIGNABLE against MapType.getKeyType().

Source

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

                values.add(v);
            }
            MultiElements.DelayedValue value = new MultiElements.DelayedValue((MultiElementType<?>) receiver.type.unwrap(), values);
            return allTerminal ? value.bind(QueryOptions.DEFAULT) : value;
        }

        private void validateAssignableTo(String keyspace, ColumnSpecification receiver) throws InvalidRequestException
        {
            AbstractType<?> type = receiver.type.unwrap();

            if (!(type instanceof MapType))
                throw new InvalidRequestException(String.format("Invalid map literal for %s of type %s", receiver.name, receiver.type.asCQL3Type()));

            ColumnSpecification keySpec = Maps.keySpecOf(receiver);
            ColumnSpecification valueSpec = Maps.valueSpecOf(receiver);
            for (Pair<Term.Raw, Term.Raw> entry : entries)
            {
                if (!entry.left.testAssignment(keyspace, keySpec).isAssignable())
                    throw new InvalidRequestException(String.format("Invalid map literal for %s: key %s is not of type %s", receiver.name, entry.left, keySpec.type.asCQL3Type()));
                if (!entry.right.testAssignment(keyspace, valueSpec).isAssignable())
                    throw new InvalidRequestException(String.format("Invalid map literal for %s: value %s is not of type %s", receiver.name, entry.right, valueSpec.type.asCQL3Type()));
            }
        }

        public AssignmentTestable.TestResult testAssignment(String keyspace, ColumnSpecification receiver)
        {
            return testMapAssignment(receiver, entries);
        }

        @Override
        public AbstractType<?> getExactTypeIfKnown(String keyspace)
        {
            return getExactMapTypeIfKnown(entries, p -> p.getExactTypeIfKnown(keyspace));
        }

        @Override
        public AbstractType<?> getCompatibleTypeIfKnown(String keyspace)

View on GitHub (pinned to 88fd0f6a0e)

Solutions

  1. Make literal keys match the declared key type (e.g. `{1: 'a'}` for map<int,text>).
  2. Verify the key type via system_schema and update the query.
  3. Cast/convert values at the application layer before building the statement.

Example fix

// before (map<int,text>)
"UPDATE t SET m = {'1':'a'} WHERE k=?"
// after
"UPDATE t SET m = {1:'a'} WHERE k=?"
Defensive patterns

Strategy: validation

Validate before calling

// keys must be literals assignable to the map key type, e.g. map<int,?>
Object k = entry.getKey();
if (!(k instanceof Integer)) throw new IllegalArgumentException("key must be int, got " + k.getClass());

Try / catch

try { session.prepare(sql); } catch (InvalidRequestException e) { if (e.getMessage().contains("key") && e.getMessage().contains("is not of type")) { /* fix literal key types */ } else throw e; }

Prevention

When it happens

Trigger: Preparing e.g. `SET m = {'text-key': 1}` where the map's key type is int (map<int,text>), or mixing key types like timestamps vs strings in the literal.

Common situations: Quoting numbers so they become strings against int keys; schema changed key type; drivers sending JSON-ish literals with stringified keys.

Understand the failure class

Background: Type mismatch errors: IllegalArgumentException, TypeError and type guards across 150 open-source libraries — this error's family across 150 libraries.

Related errors

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