apache/seatunnel · error · SeaTunnelException

Failed to read schema for table %s

Error message

Failed to read schema for table %s 

What it means

SqlServerSchema.readTableSchema reads the schema of a table from SQL Server metadata; if the JDBC metadata query throws SQLException it wraps it in a SeaTunnelException. This happens while getTableSchema resolves column types for a captured table.

Source

Thrown at seatunnel-connectors-v2/connector-cdc/connector-cdc-sqlserver/src/main/java/org/apache/seatunnel/connectors/seatunnel/cdc/sqlserver/utils/SqlServerSchema.java:83

                    tables,
                    tableId.catalog(),
                    tableId.schema(),
                    connectorConfig.getTableFilters().dataCollectionFilter(),
                    null,
                    false);
            for (TableId id : tables.tableIds()) {
                if (tableMap.containsKey(id)) {
                    Table table =
                            CatalogTableUtils.mergeCatalogTableConfig(
                                    tables.forTable(id), tableMap.get(id));
                    TableChanges.TableChange tableChange =
                            new TableChanges.TableChange(
                                    TableChanges.TableChangeType.CREATE, table);
                    schemasByTableId.put(id, tableChange);
                }
            }
        } catch (SQLException e) {
            throw new SeaTunnelException(
                    String.format("Failed to read schema for table %s ", tableId), e);
        }

        if (!schemasByTableId.containsKey(tableId)) {
            throw new SeaTunnelException(
                    String.format("Can't obtain schema for table %s ", tableId));
        }

        return schemasByTableId.get(tableId);
    }
}

View on GitHub (pinned to cf67b549a7)

Solutions

1. Confirm the database connection parameters (host, port, user, password) are correct and the server is reachable
2. Verify the table identifier exists and is accessible with the configured credentials
3. Check the nested SQLException for the exact JDBC error code and address it (network, auth, naming)
4. Retry; transient network glitches during startup commonly cause this

// Pre-flight: verify metadata is readable
try (Connection c = DriverManager.getConnection(url, user, pass)) {
    DatabaseMetaData md = c.getMetaData();
    try (ResultSet rs = md.getColumns(null, "dbo", "Orders", null)) {
        if (!rs.next()) throw new IllegalStateException("No schema visible for table");
    }
}

// Job-level retry for transient metadata read failures
try {
    startJob(cfg);
} catch (SeaTunnelException e) {
    if (e.getMessage().startsWith("Failed to read schema")) {
        retryWithBackoff(() -> startJob(cfg), 3);
    } else throw e;
}

When it happens

Trigger: SQLException from the metadata query in readTableSchema (called by getTableSchema) — e.g. connection failure or invalid table identifier passed to the schema lookup.

Common situations: Database unreachable or credentials wrong; table dropped before schema read; special characters in schema/table names not escaped; firewall blocking the connection during startup.

Understand the failure class

Background: Schema validation failed / invalid input schema: payload rejected because its shape doesn't match the expected schema — this error's family across 28 libraries.

Related errors

• Can't obtain schema for table %s
• Unsupported alter table event:
• Unsupported alter table event:
• Unsupported type:
• Unsupported SQL type:

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