apache/hadoop · error · ConfigurationException

The keystore password parameter is empty for the ZooKeeper c

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.

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)

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.