apache/iceberg · error · RuntimeException

Failed to list namespace under namespace: <namespace> in Hiv

Error message

Failed to list namespace under namespace: <namespace> in Hive Metastore

What it means

Thrown by HiveCatalog.alterHiveDataBase when the Hive Metastore client call getDatabase(name) fails with a generic Thrift exception (TException) while altering namespace properties. It is a plain RuntimeException wrapping the underlying Thrift cause, not a typed Iceberg exception. It usually indicates a metastore connectivity, protocol, or server-side problem rather than a missing namespace (that case throws NoSuchNamespaceException first).

Source

Thrown at hive-metastore/src/main/java/org/apache/iceberg/hive/HiveCatalog.java:681

    LOG.debug("Successfully removed properties {} from {}", properties, namespace);

    // Always successful, otherwise exception is thrown
    return true;
  }

  private void alterHiveDataBase(Namespace namespace, Database database) {
    try {
      clients.run(
          client -> {
            client.alterDatabase(namespace.level(0), database);
            return null;
          });

    } catch (NoSuchObjectException | UnknownDBException e) {
      throw new NoSuchNamespaceException(e, "Namespace does not exist: %s", namespace);

    } catch (TException e) {
      throw new RuntimeException(
          "Failed to list namespace under namespace: " + namespace + " in Hive Metastore", e);

    } catch (InterruptedException e) {
      Thread.currentThread().interrupt();
      throw new RuntimeException(
          "Interrupted in call to getDatabase(name) " + namespace + " in Hive Metastore", e);
    }
  }

  @Override
  public Map<String, String> loadNamespaceMetadata(Namespace namespace) {
    if (!isValidateNamespace(namespace)) {
      throw new NoSuchNamespaceException("Namespace does not exist: %s", namespace);
    }

    try {
      Database database = clients.run(client -> client.getDatabase(namespace.level(0)));
      Map<String, String> metadata = convertToMetadata(database);

View on GitHub (pinned to 86d9c8fc54)

Solutions

1. Inspect the wrapped cause (getCause()) to identify the actual TException and fix the underlying metastore connectivity or protocol issue.
2. Verify hive.metastore.uris is reachable (telnet/nc to the HMS host:port) and the metastore is running.
3. Retry the operation; TException from HMS is often transient.
4. Check thrift protocol/version compatibility between the iceberg-hive-metastore client and the HMS server version.

Example fix

// before
catalog.setProperties(ns, props); // raw RuntimeException on TException
// after
try {
  catalog.setProperties(ns, props);
} catch (RuntimeException e) {
  if (e.getCause() instanceof TException) {
    // retry or surface HMS connectivity problem
  }
  throw e;
}

// verify HMS reachability before the call
try (Socket s = new Socket(hmsHost, hmsPort)) { /* reachable */ }

try {
  catalog.setProperties(ns, props);
} catch (RuntimeException e) {
  if (e.getCause() instanceof TException) { /* retry/backoff or alert on HMS health */ }
  throw e;
}

When it happens

Trigger: Calling HiveCatalog.setProperties or removeProperties when client.getDatabase throws TException (e.g. HMS connection dropped, thrift protocol mismatch, transient metastore failure).

Common situations: Hive Metastore is down or restarted mid-call; network/timeout between client and HMS; hive-metastore thrift version mismatch; Kerberos/authentication failure surfacing as TException.

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

• Failed to create namespace ${namespace} in Hive Metastore
• Failed to check table existence of ${baseTableIdentifier}
• Failed to check view existence of ${viewIdentifier}
• Failed to list all namespace: <namespace> in Hive Metastore
• Failed to drop namespace <namespace> in Hive Metastore

AI-assisted analysis of apache/iceberg@86d9c8fc54 (2026-09-12). Data as JSON: /api/errors/a19e505cfb210cd3. Report an issue: GitHub.