apache/seatunnel · error · ClickhouseConnectorException

Failed to execute query: %s

Error message

Failed to execute query: %s

What it means

Thrown by ClickhouseValueReader.run() when ClickHouse's JDBC driver raises a ClickHouseException while executing the streaming read SQL (executeSql). The connector wraps it in a ClickhouseConnectorException with QUERY_DATA_ERROR and the message 'Failed to execute query: %s' plus the original exception. It means the query driving the whole-part/streamed read failed at execution time on the server or connection.

Source

Thrown at seatunnel-connectors-v2/connector-clickhouse/src/main/java/org/apache/seatunnel/connectors/seatunnel/clickhouse/source/ClickhouseValueReader.java:478

                                                                                .convertToSeaTunnelRow(
                                                                                        record,
                                                                                        rowTypeInfo,
                                                                                        clickhouseSourceTable
                                                                                                .getTablePath()
                                                                                                .getFullName());
                                                                try {
                                                                    rowQueue.put(seaTunnelRow);
                                                                } catch (InterruptedException e) {
                                                                    throw new ClickhouseConnectorException(
                                                                            ClickhouseConnectorErrorCode
                                                                                    .ROW_BATCH_GET_FAILED,
                                                                            e);
                                                                }
                                                            });
                                        }
                                    }
                                } catch (ClickHouseException e) {
                                    throw new ClickhouseConnectorException(
                                            ClickhouseConnectorErrorCode.QUERY_DATA_ERROR,
                                            String.format(
                                                    "Failed to execute query: %s", executeSql),
                                            e);
                                } finally {
                                    eos.set(true);
                                    log.info("StreamValueReader finished reading data");
                                }
                            }
                        },
                        "clickhouse-stream-reader-" + clickhouseSourceSplit.getSplitId());

        public boolean hasNext() {
            List<SeaTunnelRow> rows = new ArrayList<>();
            while (!eos.get() || !rowQueue.isEmpty()) {
                if (!rowQueue.isEmpty()) {
                    try {
                        SeaTunnelRow seaTunnelRow = rowQueue.take();

View on GitHub (pinned to cf67b549a7)

Solutions

1. Read the wrapped ClickHouseException cause for the exact server error code and message, then fix that (e.g., grant SELECT, restore table, raise memory limits)
2. Run the executeSql shown in the error manually with clickhouse-client to reproduce and see the server-side error
3. Verify connectivity/auth to the shard host and that the tablePath resolves to an existing table
4. Tune query limits (max_execution_time, max_memory_usage) or reduce read scope if the query was killed for resource limits

Example fix

// before (no limit, killed on large table)
String executeSql = "SELECT * FROM " + tablePath.getFullName();
// after
String executeSql = "SELECT * FROM " + tablePath.getFullName() + " SETTINGS max_execution_time = 600, max_memory_usage = 10000000000";

// Validate connectivity, auth, and table existence before the job
try (Connection c = DriverManager.getConnection(jdbcUrl, user, pass)) {
    ResultSet rs = c.createStatement().executeQuery(
        "EXISTS TABLE " + tablePath.getFullName());
    rs.next();
    if (rs.getInt(1) != 1) throw new IllegalStateException("Table missing: " + tablePath.getFullName());
}

try {
    reader.run();
} catch (ClickhouseConnectorException e) {
    if (e.getErrorCode() == ClickhouseConnectorErrorCode.QUERY_DATA_ERROR
        && e.getMessage().startsWith("Failed to execute query:")) {
        Throwable cause = e.getCause(); // ClickHouseException with server error code
        // inspect cause.getErrorCode() and retry transient codes with backoff
    }
    throw e;
}

When it happens

Trigger: executeSql sent via the ClickHouse JDBC client during run() returns a ClickHouseException: server-side query error (syntax, missing table, permissions, memory limit), connection reset, or query killed due to timeout/max_execution_time.

Common situations: Table or database renamed/dropped before the job ran; ClickHouse user lacking grants; query hitting memory/max_execution_time limits on large tables; shard host down or DNS failure; ClickHouse server version rejecting the generated SQL.

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

• Failed to read data from sql %s, shard: %s, splitId %s, mess
• Failed to get clickhouse server config: {}
• Failed to split chunks for table " + tableId
• Error to discover tables:
• Error to check tables:

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