apache/seatunnel · error · CatalogException

Failed getting SYNONYM

Error message

Failed getting SYNONYM %s

What it means

When the requested table is actually a SAP HANA SYNONYM, SapHanaCatalog.getTable() resolves the real target by querying the SYNONYMS system view and rewriting the TablePath to the referenced OBJECT_SCHEMA/OBJECT_NAME. If that lookup fails for any reason, it throws a CatalogException with 'Failed getting SYNONYM <fullName>'. This is a wrapper exception; the underlying cause (SQL error, connection problem, unexpected result set) is attached.

Solutions

1. Inspect the cause chain to find the actual SQL/connection error.
2. Check that the connecting user can SELECT from the SYNONYMS system view for that schema.
3. Manually run the SYNONYMS query in HANA SQL console with the same SCHEMA_NAME/SYNONYM_NAME to reproduce.
4. Avoid special quote characters in schema/synonym identifiers, or fix naming to unquoted-safe identifiers.

// java
// confirm the synonym is resolvable before getTable
List<String> synonyms = catalog.listSynonym(tablePath.getDatabaseName());
boolean isSynonym = synonyms.contains(tablePath.getTableName());

// java
try {
    CatalogTable t = catalog.getTable(tablePath);
} catch (CatalogException e) {
    if (e.getMessage().startsWith("Failed getting SYNONYM")) {
        LOG.error("synonym resolution failed", e.getCause());
    }
    throw e;
}

When it happens

Trigger: The table name is in listSynonym(databaseName) but the SYNONYMS system-view query (prepared from a string-formatted SQL with schema and synonym name interpolated) throws — e.g. synonym names containing quote characters breaking the SQL, connection lost, or permission denied reading SYNONYMS.

Common situations: Synonyms with quotes/special characters in schema or name; user lacks privilege on the SYNONYMS view for the schema; dangling synonyms whose OBJECT_SCHEMA/OBJECT_NAME rows cannot be read; concurrent synonym redefinition.

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

• Failed to querySQLResult
• create table error
• 查询数据库是否存在失败:
• execute sql error
• Failed creating database

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

Appendix: source

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

        } else {
            dbUrl = getUrlFromDatabaseName(defaultDatabase);
        }
        Connection conn = getConnection(dbUrl);
        TablePath originalTablePath = tablePath;
        if (listSynonym(tablePath.getDatabaseName()).contains(tablePath.getTableName())) {
            String sql =
                    String.format(
                            "SELECT SYNONYM_NAME, SCHEMA_NAME, OBJECT_NAME, OBJECT_SCHEMA  FROM SYNONYMS  WHERE SCHEMA_NAME = '%s' AND SYNONYM_NAME = '%s' ",
                            tablePath.getDatabaseName(), tablePath.getTableName());
            try (PreparedStatement statement = conn.prepareStatement(sql);
                    final ResultSet resultSet = statement.executeQuery()) {
                while (resultSet.next()) {
                    final String refDatabaseName = resultSet.getString("OBJECT_SCHEMA");
                    final String refTableName = resultSet.getString("OBJECT_NAME");
                    tablePath = TablePath.of(refDatabaseName, refTableName);
                }
            } catch (Exception e) {
                throw new CatalogException(
                        String.format("Failed getting SYNONYM %s", tablePath.getFullName()), e);
            }
        }
        try {
            DatabaseMetaData metaData = conn.getMetaData();
            Optional<PrimaryKey> primaryKey = getPrimaryKey(metaData, tablePath);
            List<ConstraintKey> constraintKeys = getConstraintKeys(metaData, tablePath);
            try (PreparedStatement ps = conn.prepareStatement(getSelectColumnsSql(tablePath));
                    ResultSet resultSet = ps.executeQuery()) {

                TableSchema.Builder builder = TableSchema.builder();
                buildColumnsWithErrorCheck(tablePath, resultSet, builder);
                // add primary key
                primaryKey.ifPresent(builder::primaryKey);
                // add constraint key
                constraintKeys.forEach(builder::constraintKey);
                TableIdentifier tableIdentifier = getTableIdentifier(originalTablePath);
                return CatalogTable.of(

View on GitHub (pinned to cf67b549a7)