apache/seatunnel · critical · RuntimeException

Failed to discover captured tables for enumerator

Error message

Failed to discover captured tables for enumerator

What it means

IncrementalSource.createEnumerator builds the split assigner by first discovering the captured tables (via a dialect-specific table discovery). Any exception during discovery is wrapped in a RuntimeException with this message, preserving the cause. It signals the enumerator could not determine the set of tables to capture.

Source

Thrown at seatunnel-connectors-v2/connector-cdc/connector-cdc-base/src/main/java/org/apache/seatunnel/connectors/cdc/base/source/IncrementalSource.java:349

                            new SnapshotOnlySplitAssigner<>(
                                    assignerContext,
                                    enumeratorContext.currentParallelism(),
                                    remainingTables,
                                    isTableIdCaseSensitive,
                                    dataSourceDialect);
                } else {
                    splitAssigner =
                            new HybridSplitAssigner<>(
                                    assignerContext,
                                    enumeratorContext.currentParallelism(),
                                    incrementalParallelism,
                                    remainingTables,
                                    isTableIdCaseSensitive,
                                    dataSourceDialect,
                                    offsetFactory);
                }
            } catch (Exception e) {
                throw new RuntimeException("Failed to discover captured tables for enumerator", e);
            }
        } else {
            splitAssigner =
                    new IncrementalSplitAssigner<>(
                            assignerContext, incrementalParallelism, offsetFactory);
        }

        return new IncrementalSourceEnumerator(enumeratorContext, splitAssigner);
    }

    @Override
    public SourceSplitEnumerator<SourceSplitBase, PendingSplitsState> restoreEnumerator(
            SourceSplitEnumerator.Context<SourceSplitBase> enumeratorContext,
            PendingSplitsState checkpointState)
            throws Exception {
        // Load the JDBC driver in to DriverManager
        if (driverName().isPresent()) {
            try {

View on GitHub (pinned to cf67b549a7)

Solutions

1. Read the cause chain for the real error (SQL exception, auth failure, network timeout) and fix it
2. Verify hostname, port, username, password and database-name/table-name patterns in the config
3. Grant the CDC user SELECT and metadata access on the databases/tables being captured
4. Confirm the database is reachable from SeaTunnel workers, then resubmit the job

Example fix

// before
"database-names" = ["prod_db"]
"username" = "cdc_user"   // no privileges on prod_db -> discovery fails
// after
GRANT SELECT ON prod_db.* TO 'cdc_user'@'%';
// discovery succeeds

// pre-flight: verify metadata access and that patterns match tables
try (Connection c = DriverManager.getConnection(url, user, pass);
     ResultSet rs = c.getMetaData().getTables(db, null, "%", new String[]{"TABLE"})) {
    if (!rs.next()) throw new IllegalStateException("No tables matched database-names/table-names pattern");
}

try {
    enumerator = source.createEnumerator(context);
} catch (RuntimeException e) {
    Throwable root = e.getCause();  // real discovery failure (SQL/auth/network)
    LOG.error("Table discovery failed: {}", root == null ? e : root.getMessage());
}

When it happens

Trigger: createEnumerator is invoked at job start (non-restore path) and the underlying discovery — listing tables/schemas via JDBC metadata against the source database — throws (bad credentials, missing database, network failure, driver error).

Common situations: Wrong hostname/port/credentials in CDC config, source database user lacking metadata privileges, database name pattern matching zero tables, or the database being temporarily unreachable at job startup.

Understand the failure class

Background: Database query failed: Internal Server Error 500s wrapping SQL, Prisma, and connection failures — what to check first — this error's family across 16 libraries.

Related errors

• Failed to discover remaining tables to capture
• Error to discover tables:
• Error to discover tables: ${e.getMessage()}
• Exactly once is enabled, but not found primary key or unique
• Failed to split chunks for table " + tableId

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