apache/cassandra · error · SyntaxException

Invalid or malformed CQL query string

Error message

Invalid or malformed CQL query string: %s

What it means

When CQL parsing fails with an ANTLR RecognitionException, QueryProcessor wraps it in a SyntaxException with the parser's message. This is the classic 'your CQL string is not valid grammar' error — the text does not match the CQL language grammar at all.

Solutions

1. Correct the CQL grammar error indicated by the ANTLR message (position is included in e.getMessage())
2. Check quote escaping: use '' inside string literals and double quotes for identifiers
3. Validate the statement in cqlsh first to see precise syntax errors
4. Use bind markers/values instead of ad-hoc string building

Example fix

// before
"SELECT * FROM users WHERE name = "O'Brien"" // broken quoting
// after
"SELECT * FROM users WHERE name = 'O''Brien'"

if (cql.chars().filter(ch -> ch == '\'').count() % 2 != 0) throw new IllegalArgumentException("unbalanced quotes in CQL");

try { session.execute(cql); } catch (SyntaxException e) { if (e.getMessage().startsWith("Invalid or malformed CQL")) { fixOrSurfaceSyntaxError(cql, e.getMessage()); return; } throw e; }

When it happens

Trigger: Sending a syntactically invalid CQL string through QueryProcessor.parseStatement/processQuery — missing keywords, unbalanced parentheses/quotes, wrong clause order, empty statement text.

Common situations: Hand-written or concatenated CQL with typos; missing escaping of quotes in string literals; cqlsh copy/paste artifacts (smart quotes, line breaks); clients using syntax from a different CQL version.

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.

• Parsing and encoding errors: unexpected token, malformed input — why parsers reject input and how to find the real culprit.

Related errors

• (dynamic first syntax error message from parser/lexer)
• text could not be lexed
• A TTL must be greater or equal to 0, but was
• A user type cannot contain counters
• A user type cannot contain non-frozen UDTs

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

Appendix: source

Thrown at src/java/org/apache/cassandra/cql3/QueryProcessor.java:1006

        try
        {
            return CQLFragmentParser.parseAnyUnhandled(CqlParser::query, queryStr);
        }
        catch (CassandraException ce)
        {
            throw ce;
        }
        catch (RuntimeException re)
        {
            logger.error(String.format("The statement: [%s] could not be parsed.", queryStr), re);
            throw new SyntaxException(String.format("Failed parsing statement: [%s] reason: %s %s",
                                                    queryStr,
                                                    re.getClass().getSimpleName(),
                                                    re.getMessage()));
        }
        catch (RecognitionException e)
        {
            throw new SyntaxException("Invalid or malformed CQL query string: " + e.getMessage());
        }
    }

    private static int measurePstmnt(Prepared value)
    {
        return Ints.checkedCast(ObjectSizes.measureDeep(value));
    }

    private static int getSizeOfPreparedStatementForCache(MD5Digest key, Prepared value)
    {
        if (value.pstmntSize < 0)
            throw new IllegalStateException("Precomputed prepared statement size not available");

        return Ints.checkedCast(key.size() + value.pstmntSize);
    }

    /**
     * Clear our internal statmeent cache for test purposes.

View on GitHub (pinned to 88fd0f6a0e)