apache/hadoop · error · ConfigurationException

The truststore password parameter is empty for the ZooKeeper

Error message

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

What it means

The final check in SecurityUtil.validateSslConfiguration: the truststore password must be non-empty. All four SSL fields (keystore location/password, truststore location/password) must be present together; a blank truststore password fails validation with ConfigurationException before any TLS connection is attempted.

Source

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

    }
  }

  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
   */
  public static void setSslConfiguration(ZKClientConfig zkClientConfig,
                                         TruststoreKeystore truststoreKeystore)
          throws ConfigurationException {
    setSslConfiguration(zkClientConfig, truststoreKeystore, new ClientX509Util());
  }

  public static void setSslConfiguration(ZKClientConfig zkClientConfig,
                                         TruststoreKeystore truststoreKeystore,

View on GitHub (pinned to 2add963021)

Solutions

Set the zookeeper SSL truststore password property (zookeeper.ssl.truststore.password)
Verify credential-provider aliases resolve non-empty: hadoop credential list
Check the effective config shows all four SSL fields populated
Restart the daemon and watch for the SASL/TLS handshake to confirm the config is now complete

Example fix

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

<!-- after -->
<property><name>zookeeper.ssl.truststore.location</name><value>/etc/zk/ssl/truststore.jks</value></property>
<property><name>zookeeper.ssl.truststore.password</name><value>${zk-truststore-password}</value></property>

Defensive patterns

Strategy: validation

Validate before calling

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

Prevention

Pair truststore location and password in one config unit
Use credential providers and verify alias resolution in deployment checks
Surface which of the four fields failed validation in startup errors

When it happens

Trigger: ZK SSL configured with the other three fields set but the truststore password property unset or blank, commonly when the password was meant to come from a credential provider or environment substitution that produced an empty string.

Common situations: Secrets externalized but the alias missing; config templating that drops the last property; truststores created without passwords while the validator requires the field regardless.

Related errors

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