{"record":{"id":"93c94b6191f063d6","repo":"apache/shardingsphere","slug":"42000-93c94b","errorCode":"42000","errorMessage":"You have an error in your SQL syntax: %s","messagePattern":"You have an error in your SQL syntax: (.+?)","errorType":"exception","errorClass":"SQLParsingException","httpStatus":null,"severity":"error","filePath":"parser/distsql/engine/src/main/java/org/apache/shardingsphere/distsql/parser/core/utility/UtilityDistSQLStatementParserEngine.java","lineNumber":48,"sourceCode":" */\npublic final class UtilityDistSQLStatementParserEngine {\n    \n    /**\n     * Parse SQL.\n     *\n     * @param sql SQL to be parsed\n     * @return SQL statement\n     */\n    public SQLStatement parse(final String sql) {\n        ASTNode astNode = parseToASTNode(sql);\n        return getSQLStatement(sql, (ParseASTNode) astNode);\n    }\n    \n    private ASTNode parseToASTNode(final String sql) {\n        try {\n            return SQLParserFactory.newInstance(sql, UtilityDistSQLLexer.class, UtilityDistSQLParser.class).parse();\n        } catch (final ParseCancellationException ignored) {\n            throw new SQLParsingException(sql);\n        }\n    }\n    \n    private SQLStatement getSQLStatement(final String sql, final ParseASTNode parseASTNode) {\n        if (parseASTNode.getRootNode() instanceof ErrorNode) {\n            throw new SQLParsingException(sql);\n        }\n        return (SQLStatement) (new UtilityDistSQLStatementVisitor()).visit(parseASTNode.getRootNode());\n    }\n}\n","sourceCodeStart":30,"sourceCodeEnd":59,"githubUrl":"https://github.com/apache/shardingsphere/blob/e952770a215630a3659c75d64369168cd3e26b82/parser/distsql/engine/src/main/java/org/apache/shardingsphere/distsql/parser/core/utility/UtilityDistSQLStatementParserEngine.java#L30-L59","documentation":"Thrown by UtilityDistSQLStatementParserEngine.parseToASTNode when the utility DistSQL parser (UtilityDistSQLLexer/Parser) fails with an ANTLR ParseCancellationException. Utility DistSQL covers statements like SHOW SHARDING or preview-style helpers; when the token stream violates the grammar, the parser's error strategy cancels and the SQL is wrapped in SQLParsingException (SQLState 42000).","triggerScenarios":"Calling UtilityDistSQLStatementParserEngine.parse with a statement that does not match utility DistSQL grammar: invalid PREVIEW/SHOW-like syntax, wrong clause keywords, unbalanced tokens, or a statement of another DistSQL category sent to the utility engine.","commonSituations":"Preview workflows where users pass arbitrary SQL to PREVIEW with wrong wrapping; mistyped utility commands in ops scripts; grammar changes across ShardingSphere versions; using utility DistSQL reserved words as plain identifiers.","solutions":["Verify the statement against utility DistSQL grammar (UtilityDistSQL.g4) for your version","Ensure the statement category matches the engine (utility vs kernel vs featured)","Fix quoting/escaping of embedded SQL inside PREVIEW-like statements","Upgrade if the utility grammar in your version has a known gap for the statement"],"exampleFix":"// before\nengine.parse(\"PREVIEW SELECT * FROM t WHERE\"); // incomplete inner SQL\n\n// after\nengine.parse(\"PREVIEW SELECT * FROM t WHERE id = 1\");","handlingStrategy":"try-catch","validationCode":null,"typeGuard":null,"tryCatchPattern":"try { engine.parse(sql); } catch (SQLParsingException e) { throw new UserInputException(\"Invalid utility DistSQL: \" + sql, e); }","preventionTips":["Validate PREVIEW inner SQL separately before wrapping it in DistSQL","Quote embedded SQL correctly inside utility statements","Test utility DistSQL scripts against the same proxy version in CI"],"tags":["distsql","utility","parser","syntax","antlr"],"backgroundTag":null,"analyzedSha":"e952770a215630a3659c75d64369168cd3e26b82","analyzedAt":"2026-08-14T13:54:53.392Z","schemaVersion":2},"datasetVersion":"2026-08-15T17:31:12.345Z"}