apache/hadoop · error · IOException

hadoop.zk.address is not configured.

Error message

hadoop.zk.address is not configured.

What it means

ZKCuratorManager is hadoop-common's shared Curator/ZooKeeper helper. start(authInfos, sslEnabled, zkHostPort) needs a connect string: when the zkHostPort argument is null it falls back to the hadoop.zk.address Configuration property, and if that is also unset it throws IOException at startup.

Source

Thrown at hadoop-common-project/hadoop-common/src/main/java/org/apache/hadoop/util/curator/ZKCuratorManager.java:178

  /**
   * Start the connection to the ZooKeeper ensemble.
   *
   * @param authInfos  List of authentication keys.
   * @param sslEnabled If the connection should be SSL/TLS encrypted.
   * @param zkHostPort Host:Port of the ZooKeeper.
   * @throws IOException            If the connection cannot be started.
   */
  public void start(List<AuthInfo> authInfos, boolean sslEnabled, String zkHostPort)
      throws IOException {

    ZKClientConfig zkClientConfig = new ZKClientConfig();

    // Connect to the ZooKeeper ensemble
    if (zkHostPort == null) {
      zkHostPort = conf.get(CommonConfigurationKeys.ZK_ADDRESS);
      if (zkHostPort == null) {
        throw new IOException(
            CommonConfigurationKeys.ZK_ADDRESS + " is not configured.");
      }
      LOG.debug("Configured {} as {}", CommonConfigurationKeys.ZK_ADDRESS, zkHostPort);
    }

    int numRetries = conf.getInt(CommonConfigurationKeys.ZK_NUM_RETRIES,
        CommonConfigurationKeys.ZK_NUM_RETRIES_DEFAULT);
    int zkSessionTimeout = conf.getInt(CommonConfigurationKeys.ZK_TIMEOUT_MS,
        CommonConfigurationKeys.ZK_TIMEOUT_MS_DEFAULT);
    int zkRetryInterval = conf.getInt(
        CommonConfigurationKeys.ZK_RETRY_INTERVAL_MS,
        CommonConfigurationKeys.ZK_RETRY_INTERVAL_MS_DEFAULT);
    RetryNTimes retryPolicy = new RetryNTimes(numRetries, zkRetryInterval);

    // Set up ZK auths
    List<ZKUtil.ZKAuthInfo> zkAuths = getZKAuths(conf);
    if (authInfos == null) {
      authInfos = new ArrayList<>();

View on GitHub (pinned to 2add963021)

Solutions

  1. Add hadoop.zk.address=host:port[,host:port...] to the service's core-site.xml and redeploy
  2. Or pass the connect string explicitly: zkManager.start(authInfos, false, "zk1:2181,zk2:2181")
  3. Sanity-check the exact Configuration object: conf.get("hadoop.zk.address") must return non-null in the JVM that calls start()

Example fix

<!-- before: core-site.xml lacks the property, start(authInfos) throws IOException -->
<!-- after -->
<property>
  <name>hadoop.zk.address</name>
  <value>zk1.example.com:2181,zk2.example.com:2181</value>
</property>
Defensive patterns

Strategy: validation

Validate before calling

String zk = conf.get("hadoop.zk.address");
if (zk == null || zk.trim().isEmpty()) {
  throw new IllegalStateException(
      "hadoop.zk.address missing: set it in core-site.xml or pass zkHostPort to start()");
}
zkManager.start(authInfos, sslEnabled, zk);

Try / catch

try {
  zkManager.start(authInfos, sslEnabled, null);
} catch (IOException e) {
  throw new ServiceConfigurationException("cannot start ZK client: " + e.getMessage()
      + " - check hadoop.zk.address in core-site.xml", e);
}

Prevention

When it happens

Trigger: Calling start(authInfos), start(authInfos, sslEnabled) or start(authInfos, sslEnabled, null) while the passed Configuration has no hadoop.zk.address; a Configuration built without loading the core-site.xml that defines it; a typo'd property name such as hadoop.zk.addresses.

Common situations: Enabling a ZooKeeper-backed feature on a cluster that never ran ZooKeeper; the defining XML living in a conf dir that was not deployed; test fixtures relying on a site file not on the classpath.

Related errors

AI-assisted analysis of apache/hadoop@2add963021 (2026-08-22). Data as JSON: /api/errors/90c801ec4925f9af. Report an issue: GitHub.