What causes "Failed to execute merge operation: {e.getMessage()}" in apache/seatunnel?

Check the wrapped SQLException cause for the exact driver error and fix the MERGE SQL inputs (key columns, table names).

apache/seatunnel · error · DatabendConnectorException

SQL_OPERATION_FAILED

SQL_OPERATION_FAILED

Error message

Failed to execute merge operation: {e.getMessage()}

What it means

Thrown by DatabendSinkAggregatedCommitter when the JDBC MERGE statement executed during commit (or close-time flush) fails with a SQLException. DatabendConnectorException wraps the driver message and original exception. It means the upsert into the Databend target table could not be executed.

Source

Thrown at seatunnel-connectors-v2/connector-databend/src/main/java/org/apache/seatunnel/connectors/seatunnel/databend/sink/DatabendSinkAggregatedCommitter.java:162

        return new ArrayList<>();
    }

    /** Perform merge from CDC stream to target table. */
    private void performMerge() {
        // Merge all the data from raw table to target table
        String mergeSql = generateMergeSql();
        log.info("[Instance {}] Executing MERGE INTO statement: {}", instanceId, mergeSql);

        try (Statement stmt = connection.createStatement()) {
            stmt.execute(mergeSql);
            log.info("[Instance {}] Merge operation completed successfully", instanceId);
        } catch (SQLException e) {
            log.error(
                    "[Instance {}] Failed to execute merge operation: {}",
                    instanceId,
                    e.getMessage(),
                    e);
            throw new DatabendConnectorException(
                    DatabendConnectorErrorCode.SQL_OPERATION_FAILED,
                    "Failed to execute merge operation: " + e.getMessage(),
                    e);
        }
    }

    private String generateMergeSql() {
        StringBuilder sql = new StringBuilder();
        sql.append(String.format("MERGE INTO %s.%s a ", database, table));
        sql.append("USING (SELECT ");

        // Add all columns from raw_data
        if (catalogTable != null && catalogTable.getSeaTunnelRowType() != null) {
            String[] fieldNames = catalogTable.getSeaTunnelRowType().getFieldNames();
            for (int i = 0; i < fieldNames.length; i++) {
                if (i > 0) {
                    sql.append(", ");
                }

View on GitHub (pinned to cf67b549a7)

Solutions

Check the wrapped SQLException cause for the exact driver error and fix the MERGE SQL inputs (key columns, table names).
Verify the target table exists and the sink user has INSERT/UPDATE grants.
Test connectivity to Databend (host/port/credentials) and retry the job from the last checkpoint.
If SQL is invalid due to schema drift, recreate the target table to match the SeaTunnel catalog schema.

Example fix

// before
String mergeSql = "MERGE INTO " + table + " USING source ON id = id ..."; // ambiguous ON clause
// after
String mergeSql = "MERGE INTO " + table + " t USING (SELECT ? AS id) s ON t.id = s.id WHEN MATCHED THEN UPDATE ...";

Defensive patterns

Strategy: try-catch

Validate before calling

// before running the job:
// SHOW GRANTS FOR user; DESCRIBE target_table;
// confirm merge key columns exist and user has INSERT/UPDATE privileges

Try / catch

try { committer.commit(committables); } catch (DatabendConnectorException e) { if (e.getCause() instanceof SQLException sqlEx) { log.error("MERGE failed: {} state={}", sqlEx.getMessage(), sqlEx.getSQLState()); } throw e; }

Prevention

Always wrap committer.commit() in try-catch and inspect the SQLException cause/SQLState.
Verify merge key columns exist in the target table before the job starts.
Keep checkpoints enabled so commits can be retried after transient failures.
Monitor Databend availability from workers before large commits.

When it happens

Trigger: performMerge executes connection.prepareStatement(mergeSql).executeUpdate() and the driver throws: syntax error in generated MERGE SQL, target table missing, unique key mismatch, permission denied, connection dropped mid-commit.

Common situations: Merge-on-write key configured with columns that don't exist in the target table; table dropped between checkpoint and commit; network interruption to Databend during a long commit; insufficient grants for the sink user.

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 apache/seatunnel@cf67b549a7 (2026-09-10). Data as JSON: /api/errors/66837942ae6121af. Report an issue: GitHub.