apache/seatunnel · error · SeaTunnelException

Failed to read schema for table ${tableId}

Error message

Failed to read schema for table ${tableId} 

What it means

PostgresSchema.readTableSchema queries PostgreSQL catalogs (via JDBC) to build the Table schema for a given TableId. If the JDBC query itself throws a SQLException, it is rethrown as a SeaTunnelException with 'Failed to read schema for table <id>' and the SQL error attached as the cause.

Source

Thrown at seatunnel-connectors-v2/connector-cdc/connector-cdc-postgres/src/main/java/org/apache/seatunnel/connectors/seatunnel/cdc/postgres/utils/PostgresSchema.java:85

                    tableIdWithoutCatalog.catalog(),
                    tableIdWithoutCatalog.schema(),
                    connectorConfig.getTableFilters().dataCollectionFilter(),
                    null,
                    false);
            for (TableId id : tables.tableIds()) {
                TableId idWithCatalog = new TableId(tableId.catalog(), id.schema(), id.table());
                if (tableMap.containsKey(idWithCatalog)) {
                    Table table =
                            CatalogTableUtils.mergeCatalogTableConfig(
                                    tables.forTable(id), tableMap.get(idWithCatalog));
                    TableChanges.TableChange tableChange =
                            new TableChanges.TableChange(
                                    TableChanges.TableChangeType.CREATE, table);
                    schemasByTableId.put(idWithCatalog, 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. Inspect the chained cause for the real SQLException (connection refused vs privilege denied)
2. Verify connection parameters (host, port, database, user, password) with psql
3. Grant the CDC user USAGE on the schema and SELECT on the table / catalog visibility
4. Retry — transient network issues at startup are the common cause

// check the connection and privileges before schema read
SELECT has_schema_privilege('cdc_user','public','USAGE');

try { schema = postgresSchema.getTableSchema(tableId); } catch (SeaTunnelException e) {
    log.error("schema read failed: {}", e.getCause(), e); throw e;
}

When it happens

Trigger: The catalog query (information_schema / JDBC DatabaseMetaData calls) fails — connection error, insufficient privileges to read catalogs, invalid identifier passed to the query, or database unreachable while reading the schema before snapshotting/streaming starts.

Common situations: Wrong hostname/port/database in the CDC source config; the CDC user cannot see the schema (missing USAGE on schema); transient network failure during job startup; quoting issues with mixed-case identifiers.

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

• Snapshotting of table ${table.id()} failed
• Failed to build the split data read statement.
• Failed creating table %s
• Failed to split chunks for table " + tableId
• Error to discover tables:

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