apache/seatunnel · error · SeaTunnelException

failed commit file to clickhouse

Error message

failed commit file to clickhouse

What it means

The ClickHouse file sink aggregate committer attaches staged files to ClickHouse during commit; a ClickHouseException from the attach operation is wrapped in this generic SeaTunnelException, failing the commit. The staged files for that shard were not successfully committed to the table.

Source

Thrown at seatunnel-connectors-v2/connector-clickhouse/src/main/java/org/apache/seatunnel/connectors/seatunnel/clickhouse/sink/file/ClickhouseFileSinkAggCommitter.java:76

                proxy.getClickhouseTable(
                        proxy.getClickhouseConnection(),
                        fileReaderOption.getShardMetadata().getDatabase(),
                        fileReaderOption.getShardMetadata().getTable());
    }

    @Override
    public List<CKFileAggCommitInfo> commit(List<CKFileAggCommitInfo> aggregatedCommitInfo)
            throws IOException {
        aggregatedCommitInfo.forEach(
                commitInfo ->
                        commitInfo
                                .getDetachedFiles()
                                .forEach(
                                        (shard, files) -> {
                                            try {
                                                this.attachFileToClickhouse(shard, files);
                                            } catch (ClickHouseException e) {
                                                throw new SeaTunnelException(
                                                        "failed commit file to clickhouse", e);
                                            }
                                        }));
        return new ArrayList<>();
    }

    @Override
    public CKFileAggCommitInfo combine(List<CKFileCommitInfo> commitInfos) {
        Map<Shard, List<String>> files = new HashMap<>();
        commitInfos.forEach(
                infos ->
                        infos.getDetachedFiles()
                                .forEach(
                                        (shard, file) -> {
                                            if (files.containsKey(shard)) {
                                                files.get(shard).addAll(file);
                                            } else {
                                                files.put(shard, file);

View on GitHub (pinned to cf67b549a7)

Solutions

1. Inspect the wrapped ClickHouseException cause for the server-side attach failure reason
2. Verify the commit user has the privileges to attach files on each shard and that disk space is sufficient
3. Confirm the staged file schema matches the target table; fix schema drift and retry the commit

When it happens

Trigger: attachFileToClickhouse throws ClickHouseException while committing detached files for a shard — e.g. schema/format mismatch of the staged files, permissions, disk space, or server error on the destination shard; raised in ClickhouseFileSinkAggCommitter.commit.

Common situations: ClickHouse user lacks permission to attach files, target shard's table schema diverged from the staged file schema, disk full on the ClickHouse node, or transient server failures during commit.

Understand the failure class

Background: "API error: {status}" and "HTTP 401/403/404/429/5xx" errors: non-2xx HTTP responses explained — this error's family across 27 libraries.

Related errors

• Failed getting table %s
• Truncate table failed
• Failed EXECUTE SQL in catalog %s
• Unsupported action type:
• Unsupported operation

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