apache/seatunnel · error · CatalogException

Failed getting table {tablePath.getFullName()}

Error message

Failed getting table {tablePath.getFullName()}

What it means

After the existence check passes, AbstractJdbcCatalog.getTable() reads metadata (columns, PKs, constraints, comment) and wraps any unexpected Exception into CatalogException('Failed getting table <name>'). SeaTunnelRuntimeExceptions are rethrown as-is so typed errors propagate unchanged.

Source

Thrown at seatunnel-connectors-v2/connector-jdbc/src/main/java/org/apache/seatunnel/connectors/seatunnel/jdbc/catalog/AbstractJdbcCatalog.java:252

            TableSchema.Builder tableSchemaBuilder =
                    buildColumnsReturnTablaSchemaBuilder(tablePath, conn);
            // add primary key
            primaryKey.ifPresent(tableSchemaBuilder::primaryKey);
            // add constraint key
            constraintKeys.forEach(tableSchemaBuilder::constraintKey);
            TableIdentifier tableIdentifier = getTableIdentifier(tablePath);
            return CatalogTable.of(
                    tableIdentifier,
                    tableSchemaBuilder.build(),
                    buildConnectorOptions(tablePath),
                    getPartitionKeys(conn, tablePath),
                    comment.orElse(""),
                    catalogName);

        } catch (SeaTunnelRuntimeException e) {
            throw e;
        } catch (Exception e) {
            throw new CatalogException(
                    String.format("Failed getting table %s", tablePath.getFullName()), e);
        }
    }

    protected TableSchema.Builder buildColumnsReturnTablaSchemaBuilder(
            TablePath tablePath, Connection conn) throws SQLException {
        TableSchema.Builder columnsBuilder = TableSchema.builder();
        try (PreparedStatement ps = conn.prepareStatement(getSelectColumnsSql(tablePath));
                ResultSet resultSet = ps.executeQuery()) {
            buildColumnsWithErrorCheck(tablePath, resultSet, columnsBuilder);
        }
        return columnsBuilder;
    }

    protected List<String> getPartitionKeys(Connection connection, TablePath tablePath)
            throws SQLException {
        return Collections.emptyList();
    }

View on GitHub (pinned to cf67b549a7)

Solutions

  1. Inspect the wrapped cause for the exact failing metadata query and fix it (usually SQL/permission).
  2. Grant the catalog user access to information_schema / metadata tables.
  3. Check DB server version support vs the connector dialect implementation.
  4. Retry if the connection was transiently dropped; ensure getConnection pool is healthy.
  5. Exclude unsupported objects (system tables/views) from the sync config.

Example fix

// before
SELECT * FROM information_schema.columns WHERE table_name = 'orders'
-- missing schema filter
// after
SELECT * FROM information_schema.columns WHERE table_schema = 'public' AND table_name = 'orders'
Defensive patterns

Strategy: try-catch

Validate before calling

// pre-check permissions
try (Connection c = DriverManager.getConnection(url, user, pass); Statement s = c.createStatement()) { s.executeQuery("SELECT * FROM information_schema.columns LIMIT 1"); }

Try / catch

catch (CatalogException e) { log.error("getTable failed for table: {}", e.getMessage(), e.getCause()); /* inspect cause: SQL syntax, permissions, or driver issue */ }

Prevention

When it happens

Trigger: getTable(tablePath) metadata reading code (connection queries for columns/keys/comments via buildColumnsReturnTablaSchemaBuilder and related helpers) throws a non-SeaTunnelRuntimeException exception; called from getCatalogTable/tableOfQuery.

Common situations: Dialect-specific metadata SQL not supported by the server version; permission denied on information_schema/system catalogs; connection dropped mid-metadata-read; unsupported table types (views, system tables); driver quirks returning unexpected result shapes.

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

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