apache/seatunnel · critical · SeaTunnelException

Failed to read schema for table ${tableId}

Error message

Failed to read schema for table ${tableId}

What it means

MySqlSchema.readTableSchema first tries information-schema-based loading; when empty it falls back to `DESC <table>`. If that fallback query throws SQLException it is wrapped in SeaTunnelException 'Failed to read schema for table <id>'.

Source

Thrown at seatunnel-connectors-v2/connector-cdc/connector-cdc-mysql/src/main/java/org/apache/seatunnel/connectors/seatunnel/cdc/mysql/utils/MySqlSchema.java:97

        return schema;
    }

    private TableChange readTableSchema(JdbcConnection jdbc, TableId tableId) {
        Map<TableId, TableChange> tableChangeMap = new HashMap<>();
        try {
            tableChangeMap = getTableSchemaByShowCreateTable(jdbc, tableId);
            if (tableChangeMap.isEmpty()) {
                log.debug("Load schema is empty for table {}", tableId);
            }
        } catch (Exception e) {
            log.debug("Ignore exception when execute `SHOW CREATE TABLE {}` failed", tableId, e);
        }
        if (tableChangeMap.isEmpty()) {
            try {
                log.info("Fallback to use `DESC {}` load schema", tableId);
                tableChangeMap = getTableSchemaByDescTable(jdbc, tableId);
            } catch (SQLException ex) {
                throw new SeaTunnelException(
                        String.format("Failed to read schema for table %s", tableId), ex);
            }
        }
        if (!tableChangeMap.containsKey(tableId)) {
            throw new RuntimeException(String.format("Can't obtain schema for table %s", tableId));
        }

        return tableChangeMap.get(tableId);
    }

    @VisibleForTesting
    public TableChange readTableSchemaByDesc(JdbcConnection jdbc, TableId tableId) {
        try {
            return getTableSchemaByDescTable(jdbc, tableId).get(tableId);
        } catch (SQLException ex) {
            throw new SeaTunnelException(
                    String.format("Failed to read schema for table %s", tableId), ex);
        }

View on GitHub (pinned to cf67b549a7)

Solutions

1. Check the wrapped SQLException cause for the exact error
2. Verify the table still exists (`SHOW TABLES LIKE ...`) and the database/table name casing matches the server
3. GRANT SELECT/DESCRIBE privileges on the table to the SeaTunnel user
4. Avoid DDL on the table while the CDC job starts

Example fix

// before
tableId = new TableId("mydb", null, "MyTable"); // Linux MySQL is case-sensitive
// after
tableId = new TableId("mydb", null, "mytable"); // match lower_case_table_names reality

mysql -u seatunnel -p -e "DESC mydb.mytable;"
// must succeed with the same user the connector uses

try {
    startCdcJob(config);
} catch (Exception e) {
    if (e.getMessage().contains("Failed to read schema for table")) {
        log.error("Check table existence, casing, and SELECT/DESCRIBE privileges", e.getCause());
    }
}

When it happens

Trigger: getTableSchema -> readTableSchema when the information-schema result is empty and the `DESC tableId` JDBC query fails with SQLException.

Common situations: Table dropped or renamed between split enumeration and schema read; user lacks privileges to describe the table; wrong database name case (case-sensitive Linux MySQL); connection failure.

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

• Failed to read schema for table %s
• Error reading MySQL variables:
• Unexpected error while connecting to MySQL and looking at GT
• Unexpected error while connecting to MySQL and looking at pr
• Unexpected error while connecting to MySQL and looking for b

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