apache/seatunnel · error · CatalogException

Failed listing database in catalog %s

Error message

Failed listing database in catalog %s

What it means

IrisCatalog.listTables wraps any exception from running the table-listing query against the given schema into a CatalogException with message "Failed listing database in catalog %s" (the wording is misleading — it lists tables, not databases). The root cause is chained.

Source

Thrown at seatunnel-connectors-v2/connector-jdbc/src/main/java/org/apache/seatunnel/connectors/seatunnel/jdbc/catalog/iris/IrisCatalog.java:171

    @Override
    protected String getTableWithConditionSql(TablePath tablePath) {
        return String.format(
                getListTableSql(tablePath.getSchemaName()) + " and TABLE_NAME = '%s'",
                tablePath.getTableName());
    }

    @Override
    protected String getUrlFromDatabaseName(String databaseName) {
        return defaultUrl;
    }

    @Override
    public List<String> listTables(String schemaName)
            throws CatalogException, DatabaseNotExistException {
        try {
            return queryString(defaultUrl, getListTableSql(schemaName), this::getTableName);
        } catch (Exception e) {
            throw new CatalogException(
                    String.format("Failed listing database in catalog %s", catalogName), e);
        }
    }

    @Override
    public CatalogTable getTable(String sqlQuery) throws SQLException {
        Connection defaultConnection = getConnection(defaultUrl);
        return CatalogUtils.getCatalogTable(defaultConnection, sqlQuery, new IrisTypeMapper());
    }

    @Override
    public CatalogTable getTable(TablePath tablePath)
            throws CatalogException, TableNotExistException {
        if (!tableExists(tablePath)) {
            throw new TableNotExistException(catalogName, tablePath);
        }

        String dbUrl;

View on GitHub (pinned to cf67b549a7)

Solutions

  1. Check the chained cause (getCause) for the concrete SQL/connection error
  2. Verify the schemaName exists in IRIS (e.g. via IRIS management portal)
  3. Confirm the catalog user has SELECT privileges on the metadata/system tables IRIS uses
  4. Test defaultUrl connectivity with a standalone JDBC client
  5. Check IRIS version compatibility with the SQL used by getListTableSql

Example fix

// before
List<String> tables = catalog.listTables(schemaName); // CatalogException
// after
try {
    List<String> tables = catalog.listTables(schemaName);
} catch (CatalogException e) {
    LOG.error("listTables({}) failed: {}", schemaName, e.getCause());
    throw e;
}
Defensive patterns

Strategy: try-catch

Validate before calling

// check schema exists via a direct query
try (Connection c = DriverManager.getConnection(defaultUrl, user, pass);
     ResultSet rs = c.getMetaData().getSchemas(null, schemaName)) {
    if (!rs.next()) throw new IllegalStateException("Unknown IRIS schema: " + schemaName);
}

Try / catch

try {
    List<String> tables = catalog.listTables(schemaName);
} catch (CatalogException e) {
    LOG.error("listTables({}) failed: {}", schemaName, e.getCause(), e);
    throw e;
}

Prevention

When it happens

Trigger: Calling listTables(schemaName) when queryString throws: connection failure to defaultUrl, schema name does not exist, or the getListTableSql is invalid for the IRIS instance.

Common situations: Typo in schema/namespace name; IRIS credentials lacking privileges on the schema; network/firewall blocking the JDBC port; IRIS version where the system table queried by getListTableSql has a different name.

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

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