apache/iceberg · critical · RuntimeMetaException

Failed to connect to Hive Metastore

Error message

Failed to connect to Hive Metastore

What it means

HiveClientPool.newClient() wraps MetaException from creating an IMetaStoreClient connection in RuntimeMetaException with message 'Failed to connect to Hive Metastore'. It means the library could not establish a working client session with the configured Hive Metastore URI — typically a wrong thrift URI, unreachable host/port, or metastore-side startup failure.

Source

Thrown at hive-metastore/src/main/java/org/apache/iceberg/hive/HiveClientPool.java:74

    this.hiveConf.addResource(conf);
  }

  @Override
  protected IMetaStoreClient newClient() {
    try {
      try {
        return GET_CLIENT.invoke(
            hiveConf, (HiveMetaHookLoader) tbl -> null, HiveMetaStoreClient.class.getName());
      } catch (RuntimeException e) {
        // any MetaException would be wrapped into RuntimeException during reflection, so let's
        // double-check type here
        if (e.getCause() instanceof MetaException) {
          throw (MetaException) e.getCause();
        }
        throw e;
      }
    } catch (MetaException e) {
      throw new RuntimeMetaException(e, "Failed to connect to Hive Metastore");
    } catch (Throwable t) {
      if (t.getMessage() != null
          && t.getMessage().contains("Another instance of Derby may have already booted")) {
        throw new RuntimeMetaException(
            t,
            "Failed to start an embedded metastore because embedded "
                + "Derby supports only one client at a time. To fix this, use a metastore that supports "
                + "multiple clients.");
      }

      throw new RuntimeMetaException(t, "Failed to connect to Hive Metastore");
    }
  }

  @Override
  protected IMetaStoreClient reconnect(IMetaStoreClient client) {
    try {
      client.close();

View on GitHub (pinned to 86d9c8fc54)

Solutions

1. Verify hive.metastore.uris points at a reachable metastore: test with `telnet <host> <port>` or nc.
2. Check the metastore service is running (systemctl status hive-metastore or the process listing) and inspect its logs.
3. Fix Hive/Hadoop client configuration (core-site.xml, hdfs-site.xml, Kerberos principals) so the client can initialize.
4. Confirm network/DNS resolution and security groups between the client and metastore host.

Example fix

// before
conf.set("hive.metastore.uris", "thrift://metastore-wrong-host:9083");
// after
conf.set("hive.metastore.uris", "thrift://metastore.internal:9083"); // verified reachable
HiveCatalog catalog = new HiveCatalog();
catalog.setConf(conf);

// before connecting, verify reachability
String uri = conf.get("hive.metastore.uris");
URI u = new URI(uri.split(",")[0]);
try (Socket s = new Socket()) {
  s.connect(new InetSocketAddress(u.getHost(), u.getPort()), 3000); // throws if unreachable
}

try {
  catalog.initialize("hive", conf);
} catch (RuntimeMetaException e) {
  if (e.getCause() instanceof MetaException) {
    // metastore unreachable/misconfigured: alert and retry with backoff
  }
}

When it happens

Trigger: Any first HiveCatalog connection attempt: newClient() calls HiveMetaStoreClient construction, and a MetaException (other than the Derby single-client case) is rethrown wrapped. Occurs on every retry cycle exhaustion when the metastore is down or the URI is wrong.

Common situations: Wrong hive.metastore.uris (typo'd host/port); metastore service not running or behind a firewall; Kerberos/HDFS config missing so the client fails during init; embedded metastore misconfigured for tests.

Understand the failure class

Background: ECONNREFUSED and "connection refused" / "could not connect to server" errors: what they mean and how to fix them — this error's family across 44 libraries.

Related errors

• Failed to list all tables under namespace ${namespace}
• Failed to reconnect to Hive Metastore
• Cannot update JDBC catalog: Connection failed
• Failed to connect: %s
• Database Connection failed

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