zhisheng17/flink-learning · error · RuntimeException

SQL parse failed: {}

Error message

SQL parse failed:
{}

What it means

Planner.callUpdate executes a DDL/DML statement via tEnv.executeSql and wraps any SqlParserException in a RuntimeException that echoes the failing SQL. This distinguishes statement-parse failures from other execution errors so the user sees exactly which SQL text was rejected by the Flink SQL parser. It surfaces when DDL submitted for update (e.g. CREATE TABLE, ALTER) has invalid syntax or references unknown identifiers at parse time.

Source

Thrown at flink-learning-sql/flink-learning-sql-client/src/main/java/com/zhisheng/sql/planner/Planner.java:133

                case d:
                    tEnv.getConfig().setIdleStateRetention(Duration.ofDays(Long.parseLong(number)));
                    break;
                default:
                    break;
            }

        } else {
            tEnv.getConfig().getConfiguration().setString(key, value);
        }
    }


    private void callUpdate(SqlCommandParser.SqlCommandCall cmdCall) {
        String ddl = cmdCall.operands[0];
        try {
            tEnv.executeSql(ddl);
        } catch (SqlParserException e) {
            throw new RuntimeException("SQL parse failed:\n" + ddl + "\n", e);
        }
    }

    private void explain(SqlCommandParser.SqlCommandCall cmdCall) {
        String ddl = cmdCall.operands[0];
        try {
            this.isExplain = true;
            tEnv.executeSql(ddl).print();
        } catch (SqlParserException e) {
            throw new RuntimeException("SQL parse failed:\n" + ddl + "\n", e);
        }
    }

    private void callCreateFunction(SqlCommandParser.SqlCommandCall cmdCall) {
        LOG.info("create function:" + cmdCall.operands[0]);
        String ddl = cmdCall.operands[0];
        try {
            tEnv.executeSql(ddl);

View on GitHub (pinned to d731cee761)

Solutions

  1. Fix the SQL syntax in the failing statement shown in the exception message
  2. Validate connector options and data types against the Flink version's supported SQL grammar
  3. Test the statement in a SQL client / Flink SQL gateway to confirm it parses
  4. Catch SqlParserException at a higher level to log the failing DDL and continue with remaining statements if batch processing is desired

Example fix

// before
tEnv.executeSql("CREATE TABLE t (id STRING) WITH ('connector'='foo')");
// after
tEnv.executeSql("CREATE TABLE t (id STRING) WITH ('connector'='kafka', 'topic'='t', 'properties.bootstrap.servers'='localhost:9092', 'format'='json')");
Defensive patterns

Strategy: try-catch

Validate before calling

// sanity check before executeSql
if (ddl == null || ddl.trim().isEmpty()) throw new IllegalArgumentException("Empty DDL statement");

Try / catch

try {
    tEnv.executeSql(ddl);
} catch (SqlParserException e) {
    LOG.error("Invalid DDL:\n{}\nCause: {}", ddl, e.getMessage());
    throw e;
}

Prevention

When it happens

Trigger: callCommand routes a command to callUpdate, and tEnv.executeSql(ddl) throws SqlParserException because the statement's syntax is invalid or references unresolvable identifiers at parse time.

Common situations: Malformed CREATE TABLE statements (missing WITH clause connectors, bad data types), wrong catalog/database identifiers, or SQL dialect mismatches (Hive/Calcite syntax not supported by the current parser).

Understand the failure class

Background: "query failed", "%w: SQL error" — wrapped database query errors in Go libraries explained — this error's family across 3 libraries.

Related errors

AI-assisted analysis of zhisheng17/flink-learning@d731cee761 (2026-09-06). Data as JSON: /api/errors/87df3ccecb6620a3. Report an issue: GitHub.