apache/cassandra · error · SyntaxException

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

Error message

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

What it means

CQL fragment parsing (types, identifiers, etc.) failed; the raw RecognitionException/RuntimeException is wrapped into a SyntaxException with the fragment text and the underlying exception class and message. It indicates the input string could not be parsed by the CQL grammar for the given meaning (e.g. a type literal).

Source

Thrown at src/java/org/apache/cassandra/cql3/CQLFragmentParser.java:49

 */
public final class CQLFragmentParser
{

    @FunctionalInterface
    public interface CQLParserFunction<R>
    {
        R parse(CqlParser parser) throws RecognitionException;
    }

    public static <R> R parseAny(CQLParserFunction<R> parserFunction, String input, String meaning)
    {
        try
        {
            return parseAnyUnhandled(parserFunction, input);
        }
        catch (RuntimeException re)
        {
            throw new SyntaxException(String.format("Failed parsing %s: [%s] reason: %s %s",
                                                    meaning,
                                                    input,
                                                    re.getClass().getSimpleName(),
                                                    re.getMessage()));
        }
        catch (RecognitionException e)
        {
            throw new SyntaxException("Invalid or malformed " + meaning + ": " + e.getMessage());
        }
    }

    /**
     * Just call a parser method in {@link CqlParser} - does not do any error handling.
     */
    public static <R> R parseAnyUnhandled(CQLParserFunction<R> parserFunction, String input) throws RecognitionException
    {
        // Lexer and parser
        ErrorCollector errorCollector = new ErrorCollector(input);

View on GitHub (pinned to 88fd0f6a0e)

Solutions

1. Inspect the embedded reason (%s %s fields) for the underlying RecognitionException message and fix the fragment syntax accordingly
2. Validate/escape user input before embedding it in CQL literals; prefer bound statements with typed values over string literals
3. Test the fragment in cqlsh to see the precise parse error
4. Upgrade the driver/server pair so both support the literal syntax in use

Example fix

// before
String lit = "{'a','b'"; // unbalanced brace -> SyntaxException
// after
String lit = "{'a','b'}"; // or use a bound statement: stmt.setString(0, value)

// basic sanity before parsing a CQL fragment
boolean looksBalanced(String fragment) {
    int p=0,b=0,c=0;
    for (char ch : fragment.toCharArray()) {
        switch(ch){case '(':p++;break;case ')':p--;break;case '{':c++;break;case '}':c--;break;case '[':b++;break;case ']':b--;}
    }
    return p==0&&b==0&&c==0;
}

try { return CQLFragmentParser.parseAny(parserFn, input); }
catch (org.apache.cassandra.cql3.SyntaxException e) {
    logger.warn("Invalid CQL fragment: {}", input, e);
    throw new IllegalArgumentException("Malformed CQL fragment: " + input, e);
}

When it happens

Trigger: Calling CQLFragmentParser.parseAny (directly or via utilities like parseCQLLiteral/TypeParser) with a syntactically invalid string — e.g. a malformed collection literal `{'a'}` with wrong syntax, an invalid type string, or unbalanced brackets.

Common situations: Application code composing type strings or literals by hand; passing user input as CQL literals without escaping; version differences where newer literal syntax is sent to an older server.

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'
• Invalid or malformed
• (dynamic first syntax error message from parser/lexer)
• Failed parsing statement: [%s] reason: %s %s
• Multiple definitions for property '%s'

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