{"record":{"id":"4e6a628d0f692813","repo":"apache/cassandra","slug":"invalid-or-malformed-cql-query-string-s","errorCode":null,"errorMessage":"Invalid or malformed CQL query string: %s","messagePattern":"Invalid or malformed CQL query string: (.+?)","errorType":"validation","errorClass":"SyntaxException","httpStatus":null,"severity":"error","filePath":"src/java/org/apache/cassandra/cql3/QueryProcessor.java","lineNumber":1006,"sourceCode":"        try\n        {\n            return CQLFragmentParser.parseAnyUnhandled(CqlParser::query, queryStr);\n        }\n        catch (CassandraException ce)\n        {\n            throw ce;\n        }\n        catch (RuntimeException re)\n        {\n            logger.error(String.format(\"The statement: [%s] could not be parsed.\", queryStr), re);\n            throw new SyntaxException(String.format(\"Failed parsing statement: [%s] reason: %s %s\",\n                                                    queryStr,\n                                                    re.getClass().getSimpleName(),\n                                                    re.getMessage()));\n        }\n        catch (RecognitionException e)\n        {\n            throw new SyntaxException(\"Invalid or malformed CQL query string: \" + e.getMessage());\n        }\n    }\n\n    private static int measurePstmnt(Prepared value)\n    {\n        return Ints.checkedCast(ObjectSizes.measureDeep(value));\n    }\n\n    private static int getSizeOfPreparedStatementForCache(MD5Digest key, Prepared value)\n    {\n        if (value.pstmntSize < 0)\n            throw new IllegalStateException(\"Precomputed prepared statement size not available\");\n\n        return Ints.checkedCast(key.size() + value.pstmntSize);\n    }\n\n    /**\n     * Clear our internal statmeent cache for test purposes.","sourceCodeStart":988,"sourceCodeEnd":1024,"githubUrl":"https://github.com/apache/cassandra/blob/88fd0f6a0eaed8943f05ac9e8f947882b8ddc8f1/src/java/org/apache/cassandra/cql3/QueryProcessor.java#L988-L1024","documentation":"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.","triggerScenarios":"Sending a syntactically invalid CQL string through QueryProcessor.parseStatement/processQuery — missing keywords, unbalanced parentheses/quotes, wrong clause order, empty statement text.","commonSituations":"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.","solutions":["Correct the CQL grammar error indicated by the ANTLR message (position is included in e.getMessage())","Check quote escaping: use '' inside string literals and double quotes for identifiers","Validate the statement in cqlsh first to see precise syntax errors","Use bind markers/values instead of ad-hoc string building"],"exampleFix":"// before\n\"SELECT * FROM users WHERE name = \"O'Brien\"\" // broken quoting\n// after\n\"SELECT * FROM users WHERE name = 'O''Brien'\"","handlingStrategy":"try-catch","validationCode":"if (cql.chars().filter(ch -> ch == '\\'').count() % 2 != 0) throw new IllegalArgumentException(\"unbalanced quotes in CQL\");","typeGuard":null,"tryCatchPattern":"try { session.execute(cql); } catch (SyntaxException e) { if (e.getMessage().startsWith(\"Invalid or malformed CQL\")) { fixOrSurfaceSyntaxError(cql, e.getMessage()); return; } throw e; }","preventionTips":["Validate CQL syntax (cqlsh or a parser) before executing user-supplied text","Escape single quotes as '' and use double quotes for case-sensitive identifiers","Avoid copying CQL from word processors (smart quotes)","Pin client CQL syntax to the server's Cassandra version"],"tags":["cql","syntax-error","antlr","parse"],"backgroundTag":"invalid-argument-format","analyzedSha":"88fd0f6a0eaed8943f05ac9e8f947882b8ddc8f1","analyzedAt":"2026-09-10T07:29:22.284Z","contentChangedAt":"2026-09-10T07:29:22.284Z","schemaVersion":2},"datasetVersion":"2026-09-17T15:17:12.973Z"}