apache/shardingsphere · error · SQLParsingException

42000

42000

Error message

You have an error in your SQL syntax: %s

What it means

Thrown by DistSQLParserEngine.parse when a DistSQL statement cannot be parsed by any registered featured parser facade. The engine iterates all DistSQLParserFacade SPI instances; if every one either throws ParseCancellationException/SQLParsingException or the SQL is not valid for that facade, the loop completes and this terminal SQLParsingException (SQLState 42000) is thrown with the original SQL embedded. It means the input is not syntactically valid DistSQL for any supported feature dialect.

Source

Thrown at parser/distsql/engine/src/main/java/org/apache/shardingsphere/distsql/parser/core/featured/DistSQLParserEngine.java:51

 */
public final class DistSQLParserEngine {
    
    /**
     * Parse SQL.
     *
     * @param sql SQL to be parsed
     * @return SQL statement
     * @throws SQLParsingException SQL parsing exception
     */
    public SQLStatement parse(final String sql) {
        for (DistSQLParserFacade each : ShardingSphereServiceLoader.getServiceInstances(DistSQLParserFacade.class)) {
            try {
                ParseASTNode astNode = (ParseASTNode) SQLParserFactory.newInstance(sql, each.getLexerClass(), each.getParserClass()).parse();
                return getSQLStatement(sql, each, astNode);
            } catch (final ParseCancellationException | SQLParsingException ignored) {
            }
        }
        throw new SQLParsingException(sql);
    }
    
    @SneakyThrows(ReflectiveOperationException.class)
    @SuppressWarnings("rawtypes")
    private SQLStatement getSQLStatement(final String sql, final DistSQLParserFacade facade, final ParseASTNode parseASTNode) {
        if (parseASTNode.getRootNode() instanceof ErrorNode) {
            throw new SQLParsingException(sql);
        }
        SQLVisitor visitor = facade.getVisitorClass().getDeclaredConstructor().newInstance();
        return (SQLStatement) visitor.visit(parseASTNode.getRootNode());
    }
}

View on GitHub (pinned to e952770a21)

Solutions

1. Verify the statement is DistSQL, not standard SQL, and re-run it against the correct SQL entry point
2. Check DistSQL spelling/grammar against the grammar files (db-parser.distsql) for your exact version
3. Confirm the facade module for the feature (e.g. shardingsphere-encrypt-distsql) is on the classpath so its DistSQLParserFacade SPI is loadable
4. Temporarily enable ANTLR error output or debug the swallowed ParseCancellationException to learn the real offending token and line
5. If grammar differs after an upgrade, rewrite the statement per the new DistSQL documentation

Example fix

// before
sql = "CREATE ENCRYPT RULE t (CLOUMNS=(...))"; // typo CLOUMNS
engine.parse(sql); // SQLParsingException

// after
sql = "CREATE ENCRYPT RULE t (COLUMNS=(...))";
engine.parse(sql);

// Validate against known DistSQL keywords before parsing
boolean looksLikeDistSQL = sql != null && sql.trim().toUpperCase().matches("(?s).*(SHARDING|ENCRYPT|READWRITE_SPLITTING|MASK|SHADOW|SHOW|PREVIEW|DIST|SET).*");
if (!looksLikeDistSQL) throw new IllegalArgumentException("Not a DistSQL statement: " + sql);

try {
    SQLStatement stmt = engine.parse(distSql);
} catch (SQLParsingException e) {
    log.warn("Invalid DistSQL: {}", distSql);
    // surface to user / reject command; do not retry with the same input
}

When it happens

Trigger: Calling DistSQLParserEngine.parse(sql) with a statement that no featured facade's grammar accepts: misspelled keywords (e.g. 'SHOW DATBASES'), RDL/RQL/RUL syntax from an incompatible version, plain MySQL/PostgreSQL SQL passed to a DistSQL entry point, or unterminated strings/quotes. Also triggered when ParseCancellationException is swallowed silently for every facade in the catch block, masking the real ANTLR error position.

Common situations: Upgrading ShardingSphere where DistSQL grammar changed between versions; typos in admin scripts run through the proxy's DistSQL console; using feature-specific DistSQL (e.g. READWRITE_SPLITTING) when the matching facade JAR is missing from the classpath so no facade can parse it; copy-pasting standard SQL instead of DistSQL.

Related errors

• 42000
• 42000
• 42000
• 42000
• 1

AI-assisted analysis of apache/shardingsphere@e952770a21 (2026-08-14). Data as JSON: /api/errors/79c51031f5d25cf7. Report an issue: GitHub.