{"record":{"id":"d06e2a524cb33411","repo":"apache/iceberg","slug":"failed-to-connect-to-hive-metastore","errorCode":null,"errorMessage":"Failed to connect to Hive Metastore","messagePattern":"Failed to connect to Hive Metastore","errorType":"exception","errorClass":"RuntimeMetaException","httpStatus":null,"severity":"critical","filePath":"hive-metastore/src/main/java/org/apache/iceberg/hive/HiveClientPool.java","lineNumber":74,"sourceCode":"    this.hiveConf.addResource(conf);\n  }\n\n  @Override\n  protected IMetaStoreClient newClient() {\n    try {\n      try {\n        return GET_CLIENT.invoke(\n            hiveConf, (HiveMetaHookLoader) tbl -> null, HiveMetaStoreClient.class.getName());\n      } catch (RuntimeException e) {\n        // any MetaException would be wrapped into RuntimeException during reflection, so let's\n        // double-check type here\n        if (e.getCause() instanceof MetaException) {\n          throw (MetaException) e.getCause();\n        }\n        throw e;\n      }\n    } catch (MetaException e) {\n      throw new RuntimeMetaException(e, \"Failed to connect to Hive Metastore\");\n    } catch (Throwable t) {\n      if (t.getMessage() != null\n          && t.getMessage().contains(\"Another instance of Derby may have already booted\")) {\n        throw new RuntimeMetaException(\n            t,\n            \"Failed to start an embedded metastore because embedded \"\n                + \"Derby supports only one client at a time. To fix this, use a metastore that supports \"\n                + \"multiple clients.\");\n      }\n\n      throw new RuntimeMetaException(t, \"Failed to connect to Hive Metastore\");\n    }\n  }\n\n  @Override\n  protected IMetaStoreClient reconnect(IMetaStoreClient client) {\n    try {\n      client.close();","sourceCodeStart":56,"sourceCodeEnd":92,"githubUrl":"https://github.com/apache/iceberg/blob/86d9c8fc543e7c56c9f624eb725f76c9baff9570/hive-metastore/src/main/java/org/apache/iceberg/hive/HiveClientPool.java#L56-L92","documentation":"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.","triggerScenarios":"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.","commonSituations":"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.","solutions":["Verify hive.metastore.uris points at a reachable metastore: test with `telnet <host> <port>` or nc.","Check the metastore service is running (systemctl status hive-metastore or the process listing) and inspect its logs.","Fix Hive/Hadoop client configuration (core-site.xml, hdfs-site.xml, Kerberos principals) so the client can initialize.","Confirm network/DNS resolution and security groups between the client and metastore host."],"exampleFix":"// before\nconf.set(\"hive.metastore.uris\", \"thrift://metastore-wrong-host:9083\");\n// after\nconf.set(\"hive.metastore.uris\", \"thrift://metastore.internal:9083\"); // verified reachable\nHiveCatalog catalog = new HiveCatalog();\ncatalog.setConf(conf);","handlingStrategy":"retry","validationCode":"// before connecting, verify reachability\nString uri = conf.get(\"hive.metastore.uris\");\nURI u = new URI(uri.split(\",\")[0]);\ntry (Socket s = new Socket()) {\n  s.connect(new InetSocketAddress(u.getHost(), u.getPort()), 3000); // throws if unreachable\n}","typeGuard":null,"tryCatchPattern":"try {\n  catalog.initialize(\"hive\", conf);\n} catch (RuntimeMetaException e) {\n  if (e.getCause() instanceof MetaException) {\n    // metastore unreachable/misconfigured: alert and retry with backoff\n  }\n}","preventionTips":["Validate hive.metastore.uris reachability in startup health checks","Monitor metastore service availability and alert on downtime","Pin and test Hive client configuration in a smoke test before prod jobs run"],"tags":["hive","metastore","connection","network"],"backgroundTag":"connection-refused","analyzedSha":"86d9c8fc543e7c56c9f624eb725f76c9baff9570","analyzedAt":"2026-09-12T00:46:39.097Z","contentChangedAt":"2026-09-12T00:46:39.097Z","schemaVersion":2},"datasetVersion":"2026-09-14T16:17:12.679Z"}