apache/cassandra · error · InvalidTypeException

Cannot parse map value from "%s", at character %d expecting

Error message

Cannot parse map value from "%s", at character %d expecting ':' but got '%c'

What it means

Thrown while parsing a map literal when the character after a key is not the key/value separator ':'. Each entry in a CQL map literal must be 'key:value'; the parser reports the actual character found at the failing position.

Source

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

                try
                {
                    n = ParseUtils.skipCQLValue(value, idx);
                }
                catch (IllegalArgumentException e)
                {
                    throw new InvalidTypeException(
                    String.format(
                    "Cannot parse map value from \"%s\", invalid CQL value at character %d",
                    value, idx),
                    e);
                }

                K k = keyCodec.parse(value.substring(idx, n));
                idx = n;

                idx = ParseUtils.skipSpaces(value, idx);
                if (value.charAt(idx++) != ':')
                    throw new InvalidTypeException(
                    String.format(
                    "Cannot parse map value from \"%s\", at character %d expecting ':' but got '%c'",
                    value, idx, value.charAt(idx)));
                idx = ParseUtils.skipSpaces(value, idx);

                try
                {
                    n = ParseUtils.skipCQLValue(value, idx);
                }
                catch (IllegalArgumentException e)
                {
                    throw new InvalidTypeException(
                    String.format(
                    "Cannot parse map value from \"%s\", invalid CQL value at character %d",
                    value, idx),
                    e);
                }

View on GitHub (pinned to 88fd0f6a0e)

Solutions

1. Use ':' between key and value in every map entry
2. Verify the literal follows CQL map syntax: {k1:v1,k2:v2}
3. Regenerate the literal with codec.format() rather than hand formatting

Example fix

// before
mapCodec.parse("{1='a'}");
// after
mapCodec.parse("{1:'a'}");

if (value.contains("='" ) || value.matches(".*\\d\\s+'"))
    throw new IllegalArgumentException("Use ':' between map key and value: " + value);
mapCodec.parse(value);

try {
    mapCodec.parse(value);
} catch (InvalidTypeException e) {
    throw new IllegalArgumentException("Map entries must be key:value pairs — " + e.getMessage(), e);
}

When it happens

Trigger: Calling MapCodec.parse() with entries using the wrong separator, e.g. "{1='a'}" (uses '='), "{1 'a'}" (missing separator), or "{1->'a'}".

Common situations: Confusing protocol syntaxes (JSON/Python dict with ':' vs CQL requires ':' but with quoted keys); pasted literals where ':' was lost in copy/paste; generating literals from a template with wrong separator.

Understand the failure class

Background: "Invalid ... format", "must be in format X", "does not look like a ..." — invalid argument format errors across CLI tools and libraries — this error's family across 17 libraries.

Related errors

• cannot parse map value from "%s", at character %d expecting
• Cannot parse map value from "%s", invalid CQL value at chara
• Cannot parse map value from "%s", at character %d expecting
• Malformed map value "%s", missing closing '}'
• text or varchar values must be enclosed by single quotes

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