apache/hadoop · error · ConfigurationException

The keystore location parameter is empty for the ZooKeeper…

Error message

The keystore location parameter is empty for the ZooKeeper client connection.

What it means

SecurityUtil.validateSslConfiguration checks a TruststoreKeystore built from the ZooKeeper client SSL properties. If the keystore location is blank (StringUtils.isEmpty), a ConfigurationException is thrown; keystore password, truststore location and truststore password are validated immediately after. The checks enforce that mutual TLS for the ZK client is configured completely, not partially.

Solutions

Set the zookeeper SSL keystore location property (zookeeper.ssl.keystore.location) to the keystore file path
Re-check exact property names against the code that builds TruststoreKeystore
Fill the other three fields too: keystore password, truststore location, truststore password
Restart the daemon and confirm the four values appear in the effective configuration dump

Example fix

<!-- before: keystore omitted -->
<property><name>zookeeper.ssl.truststore.location</name><value>/etc/zk/ssl/truststore.jks</value></property>

<!-- after -->
<property><name>zookeeper.ssl.keystore.location</name><value>/etc/zk/ssl/keystore.jks</value></property>
<property><name>zookeeper.ssl.truststore.location</name><value>/etc/zk/ssl/truststore.jks</value></property>

Defensive patterns

Strategy: validation

Validate before calling

TruststoreKeystore ts = buildFromConf(conf);
if (org.apache.commons.lang3.StringUtils.isEmpty(ts.keystoreLocation)) {
  throw new ConfigurationException(
      "zookeeper.ssl.keystore.location is required for secure ZK connections");
}
SecurityUtil.validateSslConfiguration(ts);

Type guard

static boolean sslConfigComplete(SecurityUtil.TruststoreKeystore ts) {
  return StringUtils.isNoneEmpty(ts.keystoreLocation, ts.keystorePassword,
      ts.truststoreLocation, ts.truststorePassword);
}

Prevention

Check all four SSL fields in one place before opening the ZK connection
Add config linter rules for zookeeper.ssl.* keys
Test secure ZK connections in CI with realistic keystores

When it happens

Trigger: Enabling ZooKeeper TLS (e.g. a secure ZKResourceManager state store) where the keystore location property never reached the TruststoreKeystore, so validateSslConfiguration fails during setSslConfiguration before the ZK connection opens.

Common situations: Partial SSL migration where truststore settings were filled but the keystore was omitted; property-name typos so the location never lands in the object; configs managed per-role and the daemon's file missing the key.

Related errors

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

Appendix: source

Thrown at hadoop-common-project/hadoop-common/src/main/java/org/apache/hadoop/security/SecurityUtil.java:856

    String zkAuthConf =
        zkAuthChars != null ? String.valueOf(zkAuthChars) : null;
    try {
      zkAuthConf = ZKUtil.resolveConfIndirection(zkAuthConf);
      if (zkAuthConf != null) {
        return ZKUtil.parseAuth(zkAuthConf);
      } else {
        return Collections.emptyList();
      }
    } catch (IOException | ZKUtil.BadAuthFormatException e) {
      LOG.error("Couldn't read Auth based on {}", configKey);
      throw e;
    }
  }

  public static void validateSslConfiguration(TruststoreKeystore truststoreKeystore)
          throws ConfigurationException {
    if (org.apache.commons.lang3.StringUtils.isEmpty(truststoreKeystore.keystoreLocation)) {
      throw new ConfigurationException(
          "The keystore location parameter is empty for the ZooKeeper client connection.");
    }
    if (org.apache.commons.lang3.StringUtils.isEmpty(truststoreKeystore.keystorePassword)) {
      throw new ConfigurationException(
          "The keystore password parameter is empty for the ZooKeeper client connection.");
    }
    if (org.apache.commons.lang3.StringUtils.isEmpty(truststoreKeystore.truststoreLocation)) {
      throw new ConfigurationException(
          "The truststore location parameter is empty for the ZooKeeper client connection.");
    }
    if (org.apache.commons.lang3.StringUtils.isEmpty(truststoreKeystore.truststorePassword)) {
      throw new ConfigurationException(
          "The truststore password parameter is empty for the ZooKeeper client connection.");
    }
  }

  /**
   * Configure ZooKeeper Client with SSL/TLS connection.

View on GitHub (pinned to 2add963021)