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 by MapCodec.parse() when the CQL literal string does not start with '{' after leading whitespace. A map literal in CQL must begin with an opening brace; the parser reports the first offending character. This guarantees parse() only accepts syntactically valid map literals.

Source

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

            if (value instanceof Map)
            {
                // runtime type ok, now check key and value types
                Map<?, ?> map = (Map<?, ?>) value;
                if (map.isEmpty()) return true;
                Map.Entry<?, ?> entry = map.entrySet().iterator().next();
                return keyCodec.accepts(entry.getKey()) && valueCodec.accepts(entry.getValue());
            }
            return false;
        }

        @Override
        public Map<K, V> parse(String value)
        {
            if (value == null || value.isEmpty() || value.equalsIgnoreCase("NULL")) return null;

            int idx = ParseUtils.skipSpaces(value, 0);
            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);

            if (value.charAt(idx) == '}') return newInstance(0);

            Map<K, V> m = new HashMap<>();
            while (idx < value.length())
            {
                int n;
                try
                {
                    n = ParseUtils.skipCQLValue(value, idx);
                }
                catch (IllegalArgumentException e)
                {

View on GitHub (pinned to 88fd0f6a0e)

Solutions

1. Ensure the string is a CQL map literal starting with '{' and ending with '}'
2. Check that you are using the correct codec (MapCodec vs ListCodec/SetCodec) for the value
3. Strip non-CQL decorations (quotes, type wrappers) before parsing

Example fix

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

if (value == null || !value.trim().startsWith("{"))
    throw new IllegalArgumentException("Expected CQL map literal starting with '{': " + value);
mapCodec.parse(value);

boolean looksLikeCqlMap(String s) {
    return s != null && s.trim().startsWith("{") && s.trim().endsWith("}");
}

try {
    Map<K,V> m = mapCodec.parse(value);
} catch (InvalidTypeException e) {
    throw new IllegalArgumentException("Not a valid CQL map literal: " + value, e);
}

When it happens

Trigger: Calling MapCodec.parse() with a string whose first non-space char is not '{', e.g. parse("<1='a'>") (set/UDT style), parse("1:'a'") (missing braces), or parsing a list literal "[1,2]" with the map codec.

Common situations: Passing a string produced for a different collection type (list/set literal) to the map codec; using Python/CLI repr instead of CQL literal syntax; off-by-one substring that dropped the leading brace.

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", invalid CQL value at chara
• Cannot parse map value from "%s", at character %d expecting
• 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/3779f561c3d7759a. Report an issue: GitHub.