apache/seatunnel · critical · ConnectException

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

Error message

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

What it means

Thrown by SqlServerSnapshotSplitReadTask.createDataEventsForTable when the JDBC query that exports a snapshot split's rows throws SQLException. The task wraps it in a ConnectException naming the table, failing the snapshot phase for that split.

Source

Thrown at seatunnel-connectors-v2/connector-cdc/connector-cdc-sqlserver/src/main/java/org/apache/seatunnel/connectors/seatunnel/cdc/sqlserver/source/reader/fetch/scan/SqlServerSnapshotSplitReadTask.java:238

                            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(
            SqlSeverSnapshotContext 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. Verify the table still exists and the configured table list matches exactly (database.schema.table)
  2. Check the SQL Server login has SELECT permission on the table
  3. Check the SQLException cause in the stack trace for connection issues and fix network/timeout settings
  4. Re-run the job; if a table changes mid-snapshot, exclude it or use a consistent snapshot point
Defensive patterns

Strategy: try-catch

Validate before calling

// Validate table exists and is selectable before running the job
SELECT 1 FROM sys.tables t
JOIN sys.schemas s ON t.schema_id = s.schema_id
WHERE s.name + '.' + t.name = 'dbo.Orders';
-- and grant: GRANT SELECT ON dbo.Orders TO seatunnel_user;

Try / catch

// Operator-level: catch job failure and check the cause chain
try {
    submitJob(cfg);
} catch (Exception e) {
    if (getCause(e, SQLException.class) != null) {
        log.error("Snapshot SQL failed for table; check existence/permissions", e);
    }
    throw e;
}

Prevention

When it happens

Trigger: SQLException while executing the SELECT over the split's key range against table table.id() during createDataEvents → createDataEventsForTable — invalid table name, dropped table mid-snapshot, permissions, or connection failure.

Common situations: Table renamed/dropped between split enumeration and snapshot read; user lacks SELECT permission; database became unavailable; case-sensitive or bracket-quoted identifier mismatches in SQL Server.

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/1049da40a08b68c3. Report an issue: GitHub.