apache/seatunnel · error · CatalogException

Failed to list databases

Error message

Failed to list databases

What it means

HiveMetaStoreCatalog.listDatabases() wraps any TException thrown by the Hive Metastore client's getAllDatabases() call into a CatalogException. This is a thin passthrough: the metastore RPC itself failed (connectivity, thrift protocol, or HMS server error). The warn log about HMS version compatibility hints the call signature may differ across Hive versions.

Solutions

  1. Verify the HMS thrift URI and port are correct and reachable (telnet/nc to the metastore host:9083).
  2. Check that hive-site.xml on the classpath points to the right metastore and matches the cluster's Hive version.
  3. Set hive.metastore.client.socket.timeout and align hive.metastore.thrift.protocol/version if versions differ.
  4. Inspect the root cause (cause of the CatalogException) for auth errors (Kerberos/ldap) and fix credentials/keytabs.

Example fix

// before: relying on default auto-discovered hive-site
Catalog catalog = new HiveMetaStoreCatalog("default_hive_catalog", Map.of());
// after: supply explicit metastore URI and hive-conf-dir
Map<String, Serializable> props = new HashMap<>();
props.put("hive-conf-dir", "/etc/hive/conf");
props.put("uri", "thrift://metastore-host:9083");
Defensive patterns

Strategy: try-catch

Validate before calling

// before calling
boolean reachable = true;
try (java.net.Socket s = new java.net.Socket("metastore-host", 9083)) { }
catch (java.io.IOException e) { reachable = false; }

Try / catch

try {
    List<String> dbs = catalog.listDatabases();
} catch (CatalogException e) {
    Throwable root = e.getCause();
    // check root for TTransportException/timeout and retry or fail fast
}

Prevention

When it happens

Trigger: Calling listDatabases() when the Hive Metastore is unreachable, the thrift client fails to serialize/deserialize the request, or the HMS server rejects the getAllDatabases() RPC (e.g., incompatible Hive metastore version).

Common situations: Wrong hive-site.xml or metastore URIs in classpath; HMS service down or firewall blocking the thrift port (default 9083); Kerberos/ldap auth misconfiguration; connecting a newer client to an older HMS whose Thrift protocol version differs.

Understand the failure class

Background: "API request failed": what wrapped HTTP errors from external APIs mean and how to find the real cause — this error's family across 29 libraries.

Related errors

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

Appendix: source

Thrown at seatunnel-connectors-v2/connector-hive/src/main/java/org/apache/seatunnel/connectors/seatunnel/hive/utils/HiveMetaStoreCatalog.java:586

    @Override
    public String name() {
        return "hive";
    }

    @Override
    public String getDefaultDatabase() throws CatalogException {
        return "default";
    }

    @Override
    public List<String> listDatabases() throws CatalogException {
        try {
            return getClient().getAllDatabases();
        } catch (TException e) {
            log.warn(
                    "listDatabases failed via getAllDatabases(), check HMS version compatibility: {}",
                    e.getMessage());
            throw new CatalogException("Failed to list databases", e);
        }
    }

    @Override
    public List<String> listTables(String databaseName)
            throws CatalogException, DatabaseNotExistException {
        try {
            if (!databaseExists(databaseName)) {
                throw new DatabaseNotExistException("hive", databaseName);
            }
            return getClient().getAllTables(databaseName);
        } catch (TException e) {
            throw new CatalogException("Failed to list tables in database: " + databaseName, e);
        }
    }

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

View on GitHub (pinned to cf67b549a7)