apache/cassandra · error · SyntaxException

Invalid or malformed

Error message

Invalid or malformed 

What it means

Cassandra throws this SyntaxException from CQLFragmentParser.parseAny when the ANTLR lexer/parser raises a RecognitionException while parsing a CQL fragment. The message is generic ('Invalid or malformed <meaning>') plus the raw parser message, meaning the submitted CQL text could not be tokenized or parsed according to the grammar. It is a client-facing indication of syntactically invalid CQL.

Source

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

    }

    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);
        CharStream stream = new ANTLRStringStream(input);
        CqlLexer lexer = new CqlLexer(stream);
        lexer.addErrorListener(errorCollector);

        TokenStream tokenStream = new CommonTokenStream(lexer);
        CqlParser parser = new CqlParser(tokenStream);
        parser.addErrorListener(errorCollector);

View on GitHub (pinned to 88fd0f6a0e)

Solutions

1. Run the failing CQL string through cqlsh to see the full parser error message
2. Check for unescaped quotes, missing commas, or stray semicolons in the CQL text
3. Validate generated queries against the CQL grammar for your Cassandra version before executing
4. Escape identifiers with double quotes and literals with single quotes correctly

Example fix

// before
String cql = "SELECT * FROM users WHERE name = 'O'Brien'";
// after
String cql = "SELECT * FROM users WHERE name = 'O''Brien'";

private static boolean isPlausibleCql(String cql) { return cql != null && !cql.trim().isEmpty() && countOccurrences(cql, '\'') % 2 == 0; }

try { session.execute(cql); } catch (com.datastax.driver.core.exceptions.SyntaxException e) { log.error("Bad CQL: {}", cql, e); }

When it happens

Trigger: Calling any CQL parsing entry point (e.g. QueryProcessor.parseStatement, CQLFragmentParser.parseAny) with malformed CQL: unbalanced quotes/parentheses, unknown keywords, or a grammar-level error that is not recovered as a detailed ErrorCollector message.

Common situations: Hand-built queries with unescaped string literals or semicolons; programmatically generated CQL with missing clauses; driver-side string concatenation injecting user input; pasting CQL from another dialect (MySQL/Postgres syntax).

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)
• Multiple definition for property '%s'
• Failed parsing %s: [%s] reason: %s %s
• Could not decode JSON string as a map: %s. (String was: %s)
• Failed parsing statement: [%s] reason: %s %s

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