apache/seatunnel · error · ConnectException

Snapshotting of table ${table.id()} failed

Error message

Snapshotting of table ${table.id()} failed

What it means

createDataEventsForTable executes the snapshot SELECT (chunk query) for a table via JDBC and wraps any SQLException in a Debezium ConnectException with the message 'Snapshotting of table <id> failed', chaining the original SQL error as the cause. It signals that the bulk export of rows for one snapshot split could not be completed.

Source

Thrown at seatunnel-connectors-v2/connector-cdc/connector-cdc-postgres/src/main/java/org/apache/seatunnel/connectors/seatunnel/cdc/postgres/source/reader/snapshot/PostgresSnapshotSplitReadTask.java:270

                            snapshotSplit.splitId(),
                            Strings.duration(stop - exportStart));
                    snapshotProgressListener.rowsScanned(
                            snapshotContext.partition, table.id(), rows);
                    logTimer = getTableScanLogTimer();
                }
                dispatcher.dispatchSnapshotEvent(
                        snapshotContext.partition,
                        table.id(),
                        getChangeRecordEmitter(snapshotContext, table.id(), row),
                        snapshotReceiver);
            }
            log.info(
                    "Finished exporting {} records for split '{}', total duration '{}'",
                    rows,
                    snapshotSplit.splitId(),
                    Strings.duration(clock.currentTimeInMillis() - exportStart));
        } catch (SQLException e) {
            throw new ConnectException("Snapshotting of table " + table.id() + " failed", e);
        }
    }

    protected ChangeRecordEmitter getChangeRecordEmitter(
            PostgresSnapshotContext snapshotContext, TableId tableId, Object[] row) {
        snapshotContext.offset.event(tableId, clock.currentTime());
        return new SnapshotChangeRecordEmitter(
                snapshotContext.partition, snapshotContext.offset, row, clock);
    }

    private Threads.Timer getTableScanLogTimer() {
        return Threads.timer(clock, LOG_INTERVAL);
    }

    private Object readField(ResultSet rs, int columnIndex) throws SQLException {
        final ResultSetMetaData metaData = rs.getMetaData();
        final int columnType = metaData.getColumnType(columnIndex);

View on GitHub (pinned to cf67b549a7)

Solutions

1. Read the chained cause (getCause()) to identify the underlying SQLException
2. Check the CDC user has SELECT privilege on the snapshot tables and required schemas
3. Increase statement_timeout / idle connection timeouts and verify network stability for long snapshots
4. Re-run the job — snapshot splits are restartable; if the table was dropped, restore it or remove it from the config

Example fix

// diagnose
try { ... } catch (ConnectException e) {
    log.error("snapshot failed: {}", e.getCause()); // real SQLException
}

// preflight: SELECT privilege + reachability
try (Statement s = conn.createStatement(); ResultSet rs = s.executeQuery("SELECT 1 FROM " + tableId.table() + " LIMIT 1")) { rs.next(); }

try { task.createDataEvents(ctx); } catch (ConnectException e) {
    Throwable root = e.getCause();
    log.error("Snapshot of {} failed: {}", tableId, root == null ? e : root.getMessage());
    // snapshot splits are restartable — safe to retry
}

When it happens

Trigger: The JDBC statement that reads rows for the snapshot split throws — connection dropped mid-snapshot, statement timeout, permission denied on SELECT, the table was dropped/locked, serialization or out-of-memory during result fetch.

Common situations: Network interruption between SeaTunnel worker and Postgres during a long snapshot; the snapshot user lacking SELECT on the table; PostgreSQL restart or failover mid-job; statement_timeout cancelling the long-running snapshot query.

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 build the split data read statement.
• Snapshotting of table ${table.id()} failed
• 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/7237b50a9ef2f622. Report an issue: GitHub.