apache/seatunnel · error · CatalogException

Failed EXECUTE SQL in catalog

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.

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

• create table error
• Truncate table failed
• Unsupported action type:
• Could not delete table
• drop table error

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

Appendix: 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)