apache/seatunnel · error · CatalogException

Failed listing database in catalog {this.catalogName}

Error message

Failed listing database in catalog {this.catalogName}

What it means

AbstractJdbcCatalog.listDatabases() executes the dialect's list-databases SQL via queryString() and wraps any failure into CatalogException('Failed listing database in catalog <name>'). It is thrown when catalog metadata discovery cannot query the server for database names.

Source

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

    protected String getListDatabaseSql() {
        throw new UnsupportedOperationException();
    }

    protected String getListViewSql(String databaseName) {
        throw new UnsupportedOperationException();
    }

    protected String getDatabaseWithConditionSql(String databaseName) {
        throw CommonError.unsupportedMethod(this.catalogName, "getDatabaseWithConditionSql");
    }

    @Override
    public List<String> listDatabases() throws CatalogException {
        try {
            return queryString(defaultUrl, getListDatabaseSql(), rs -> rs.getString(1));
        } catch (Exception e) {
            throw new CatalogException(
                    String.format("Failed listing database in catalog %s", this.catalogName), e);
        }
    }

    @Override
    public boolean databaseExists(String databaseName) throws CatalogException {
        if (StringUtils.isBlank(databaseName)) {
            return false;
        }
        try {
            return querySQLResultExists(defaultUrl, getDatabaseWithConditionSql(databaseName));
        } catch (SeaTunnelRuntimeException e) {
            if (e.getSeaTunnelErrorCode().getCode().equals(UNSUPPORTED_METHOD.getCode())) {
                log.warn(
                        "The catalog: {} is not supported the getDatabaseWithConditionSql for databaseExists",
                        this.catalogName);
                return listDatabases().contains(databaseName);
            }

View on GitHub (pinned to cf67b549a7)

Solutions

  1. Check connectivity to defaultUrl (host/port/credentials) with a standalone client.
  2. Grant the catalog user permission to list databases (e.g. SHOW DATABASES / access to system catalogs).
  3. Inspect the wrapped cause; if it's SQL syntax, the dialect's list-database SQL doesn't fit your server version — upgrade connector or use a matching dialect.
  4. Verify driver and TLS configuration.
Defensive patterns

Strategy: try-catch

Validate before calling

try (Connection c = DriverManager.getConnection(defaultUrl, user, pass); ResultSet rs = c.createStatement().executeQuery("SHOW DATABASES")) { while (rs.next()) rs.getString(1); }

Try / catch

catch (CatalogException e) { log.error("listDatabases failed: {}", e.getMessage(), e.getCause()); /* check connectivity/permissions on defaultUrl */ }

Prevention

When it happens

Trigger: queryString(defaultUrl, getListDatabaseSql(), rs -> rs.getString(1)) throws any Exception — connection failure or the catalog's listDatabases SQL fails/returns unexpected results; also reachable via databaseExists().

Common situations: DB server unreachable at defaultUrl (down, firewall, wrong port); catalog user lacks permission to list databases/schemas; dialect's getListDatabaseSql unsupported on old server versions; TLS/auth failure on metadata connection.

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/32a29f41ffd69971. Report an issue: GitHub.