apache/seatunnel · error · CatalogException

Failed listing database in catalog %s

Error message

Failed listing database in catalog %s

What it means

SapHanaCatalog.listSynonym wraps any exception from queryString(getListSynonymSql(...)) into CatalogException("Failed listing database in catalog %s"). Despite the wording, the failing operation is the SYNONYMS metadata query; the real cause is chained.

Source

Thrown at seatunnel-connectors-v2/connector-jdbc/src/main/java/org/apache/seatunnel/connectors/seatunnel/jdbc/catalog/saphana/SapHanaCatalog.java:160

        return String.format(
                "SELECT VIEW_NAME FROM SYS.VIEWS WHERE SCHEMA_NAME = '%s'", databaseName);
    }

    public String getListSynonymSql(String databaseName) {
        return String.format(
                "SELECT SYNONYM_NAME FROM SYNONYMS WHERE SCHEMA_NAME = '%s'", databaseName);
    }

    public List<String> listSynonym(String databaseName)
            throws CatalogException, DatabaseNotExistException {
        if (!databaseExists(databaseName)) {
            throw new DatabaseNotExistException(this.catalogName, databaseName);
        }
        String dbUrl = getUrlFromDatabaseName(databaseName);
        try {
            return queryString(dbUrl, getListSynonymSql(databaseName), this::getTableName);
        } catch (Exception e) {
            throw new CatalogException(
                    String.format("Failed listing database in catalog %s", catalogName), e);
        }
    }

    @Override
    protected String getTableName(ResultSet rs) throws SQLException {
        return rs.getString(1);
    }

    @Override
    protected String getSelectColumnsSql(TablePath tablePath) {
        return String.format(
                SELECT_COLUMNS_SQL_TEMPLATE, tablePath.getDatabaseName(), tablePath.getTableName());
    }

    @Override
    public boolean tableExists(TablePath tablePath) throws CatalogException {
        try {

View on GitHub (pinned to cf67b549a7)

Solutions

1. Inspect the chained cause for the underlying SQLException
2. Grant the connection user access to the SYNONYMS system view
3. Sanitize/quote the schema name to avoid malformed SQL
4. Retry transient failures; verify tenant connectivity

Example fix

// before
List<String> synonyms = catalog.listSynonym(schema); // CatalogException
// after
try { List<String> synonyms = catalog.listSynonym(schema); } catch (CatalogException e) {
    log.error("listSynonym({}) failed: {}", schema, e.getCause());
}

// verify metadata access first
// SELECT COUNT(*) FROM SYS.SYNONYMS WHERE SCHEMA_NAME = ?

try { catalog.listSynonym(schema); } catch (CatalogException e) { log.error("listSynonym failed: {}", e.getCause()); /* inspect SQLException */ }

When it happens

Trigger: listSynonym(databaseName) (also reached via getTable synonym resolution) when the query SELECT SYNONYM_NAME FROM SYNONYMS WHERE SCHEMA_NAME='...' fails — connection drop, SQL error, or permissions.

Common situations: User without SELECT on SYS.SYNONYMS, wrong tenant, quoting issues in schema name embedded into the SQL, transient network failures.

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

• SQL_OPERATION_FAILED
• Failed listing database in catalog %s
• DATABASE_NOT_EXISTED
• Column ${column} not found in table ${schemaAndTableName}
• Failed to read table metadata from information_schema for {}

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