apache/seatunnel · error · CatalogException

Failed EXECUTE SQL in catalog %s

Error message

Failed EXECUTE SQL in catalog %s

What it means

ClickhouseCatalog.executeSql runs an arbitrary SQL statement against the ClickHouse server through the proxy client. Any failure is wrapped in a CatalogException formatted as 'Failed EXECUTE SQL in catalog <sql>'. Note the message embeds the SQL text, so the failing statement is directly visible in the exception.

Source

Thrown at seatunnel-connectors-v2/connector-clickhouse/src/main/java/org/apache/seatunnel/connectors/seatunnel/clickhouse/catalog/ClickhouseCatalog.java:178

    @Override
    public void truncateTable(TablePath tablePath, boolean ignoreIfNotExists)
            throws TableNotExistException, CatalogException {
        try {
            if (tableExists(tablePath)) {
                proxy.truncateTable(tablePath, ignoreIfNotExists);
            }
        } catch (Exception e) {
            throw new CatalogException("Truncate table failed", e);
        }
    }

    @Override
    public void executeSql(TablePath tablePath, String sql) {
        try {
            proxy.executeSql(sql);
        } catch (Exception e) {
            throw new CatalogException(String.format("Failed EXECUTE SQL in catalog %s", sql), e);
        }
    }

    @Override
    public boolean isExistsData(TablePath tablePath) {
        try {
            return proxy.isExistsData(tablePath.getFullName());
        } catch (ExecutionException | InterruptedException e) {
            throw new RuntimeException(e);
        }
    }

    @Override
    public void createDatabase(TablePath tablePath, boolean ignoreIfExists)
            throws DatabaseAlreadyExistException, CatalogException {
        proxy.createDatabase(tablePath.getDatabaseName(), ignoreIfExists);
    }

View on GitHub (pinned to cf67b549a7)

Solutions

1. Read the embedded SQL in the message and the 'Caused by' ClickHouse error to fix the statement syntax/dialect
2. Validate the SQL against ClickHouse syntax (e.g. run it in clickhouse-client) before invoking the catalog
3. Grant the user the privileges required by the statement, or run as a user with sufficient rights
4. Confirm server connectivity and retry transient network failures

Example fix

// before
catalog.executeSql(tablePath, "ALTER TABLE db.t MODIFY COLUMN c1 INT");
// after
catalog.executeSql(tablePath, "ALTER TABLE db.t MODIFY COLUMN c1 Int32"); // ClickHouse dialect

// dry-run the statement first
catalog.executeSql(tablePath, "EXPLAIN " + sql); // throws CatalogException with the SQL text if invalid

try {
    catalog.executeSql(tablePath, sql);
} catch (CatalogException e) {
    // e.getMessage() already embeds the failing SQL
    logger.error("executeSql failed [{}]: {}", sql, e.getCause() != null ? e.getCause().getMessage() : e.getMessage());
    throw e;
}

When it happens

Trigger: Calling executeSql(tablePath, sql) when the SQL is syntactically invalid for ClickHouse, references missing objects, or the user lacks permission; also on connection/timeout failures of the underlying proxy request.

Common situations: DDL typed for MySQL/Postgres dialect that ClickHouse rejects; executing ALTER/DROP on tables the user cannot modify; SQL containing unquoted keywords or unsupported functions; server unreachable during DDL.

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

• Truncate table failed
• Unsupported action type:
• create table error
• Preview action is not supported
• Failed getting table %s

AI-assisted analysis of apache/seatunnel@cf67b549a7 (2026-09-10). Data as JSON: /api/errors/8072ef2684687fa7. Report an issue: GitHub.