apache/hadoop · error · ConfigurationException

The keystore password parameter is empty for the ZooKeeper…

Error message

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

What it means

The second check in SecurityUtil.validateSslConfiguration: after confirming the keystore location, it requires a non-empty keystore password (StringUtils.isEmpty rejects null and blank). A blank keystore password means the client cannot open its own key material for mutual TLS, so ConfigurationException is thrown.

Solutions

Set the zookeeper SSL keystore password property (zookeeper.ssl.keystore.password) to the keystore password
If using a credential provider, verify the alias resolves: hadoop credential list -provider <path>
Ensure the property name matches exactly and has no trailing whitespace-only value
Keep file permissions on the config/keystore tight since it now holds a secret

Example fix

# before
hadoop credential create zookeeper.ssl.keystore.password -value '' -provider localjceks://file/etc/zk/ssl/creds.jceks

# after
hadoop credential create zookeeper.ssl.keystore.password -value '<real-password>' -provider localjceks://file/etc/zk/ssl/creds.jceks

Defensive patterns

Strategy: validation

Validate before calling

String pw = conf.get("zookeeper.ssl.keystore.password");
if (org.apache.commons.lang3.StringUtils.isEmpty(pw)) {
  throw new ConfigurationException(
      "zookeeper.ssl.keystore.password is required when keystore.location is set");
}

Prevention

Resolve credential-provider aliases during deploy and fail on empty values
Never assume a blank password works because the keystore was created without one
Log (never print) resolved booleans for each SSL secret at startup

When it happens

Trigger: ZK SSL configured with a keystore location but the keystore password property is unset or empty, e.g. the password was expected from a credential provider that failed to resolve, leaving the field blank in the TruststoreKeystore.

Common situations: Passwords migrated to CredentialProvider/Hadoop KeyStore but the alias lookup returns nothing; passwords omitted in templated configs; values containing only whitespace.

Related errors

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

Appendix: source

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

      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.
   * @param zkClientConfig ZooKeeper Client configuration
   * @param truststoreKeystore truststore keystore, that we use to set the SSL configurations
   * @throws ConfigurationException if the SSL configs are empty
   */

View on GitHub (pinned to 2add963021)