apache/cassandra · error · SyntaxException

Failed parsing statement: [%s] reason: %s %s

Error message

Failed parsing statement: [%s] reason: %s %s

What it means

QueryProcessor.parseStatement catches RuntimeExceptions thrown while parsing/validating a CQL string and rethrows them as SyntaxException, logging the full stack trace at ERROR. It indicates the CQL text could not be turned into a statement object, though not by a grammar (RecognitionException) failure — usually a runtime error raised by post-parse semantic setup.

Source

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

        catch (RequestValidationException e)
        {
            throw new IllegalArgumentException(e.getMessage(), e);
        }
    }
    public static CQLStatement.Raw parseStatement(String queryStr) throws SyntaxException
    {
        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)

View on GitHub (pinned to 88fd0f6a0e)

Solutions

1. Fix the CQL statement syntax; check the server log for the full 'could not be parsed' stack trace to find the root RuntimeException
2. Validate/escape user input before interpolating it into CQL
3. Use bind markers instead of string-concatenating values
4. Confirm the syntax is supported by the server's Cassandra version

Example fix

// before
String cql = "SELECT * FROM t WHERE k IN (" + ids.join(")(") + ")"; // malformed
// after
String cql = "SELECT * FROM t WHERE k IN (" + ids.stream().map(i -> "?").collect(joining(",")) + ")";

// basic sanity before sending
if (cql == null || cql.trim().isEmpty()) throw new IllegalArgumentException("empty CQL");

try { session.execute(cql); } catch (SyntaxException e) { log.error("Bad CQL [{}]: {}", cql, e.getMessage()); throw new IllegalArgumentException("malformed CQL", e); }

When it happens

Trigger: Calling QueryProcessor.parseStatement (directly or via processQuery/prepare) with a CQL string whose parsing path throws a RuntimeException — e.g. invalid literals, unresolvable functions/aggregates triggered during statement construction, malformed collection literals.

Common situations: Queries built by string concatenation with malformed values; version skew where new CQL syntax is sent to an older server; bugs in custom or generated CQL; quoted identifiers or string escapes that break later validation.

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

• Multiple definition for property '%s'
• Failed parsing %s: [%s] reason: %s %s
• Invalid or malformed
• (dynamic first syntax error message from parser/lexer)
• Cannot parse constraint value from <term> for column '<colum

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