apache/hadoop · error · IOException

The SSL encryption is enabled for the component's ZooKeeper

Error message

The SSL encryption is enabled for the component's ZooKeeper client connection, however the hadoop.zk.ssl.truststore.password  parameter is empty.

What it means

The final check of validateSslConfiguration requires hadoop.zk.ssl.truststore.password to be non-empty. This gtest-era guard fails fast: without the truststore password the TLS handshake cannot proceed, so start() throws IOException instead of hanging later.

Source

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

      throw new IOException(
          "The SSL encryption is enabled for the component's ZooKeeper client connection, "
              + "however the " + CommonConfigurationKeys.ZK_SSL_KEYSTORE_LOCATION + " " +
              "parameter is empty.");
    }
    if (StringUtils.isEmpty(config.get(CommonConfigurationKeys.ZK_SSL_KEYSTORE_PASSWORD))) {
      throw new IOException(
          "The SSL encryption is enabled for the component's " + "ZooKeeper client connection, "
              + "however the " + CommonConfigurationKeys.ZK_SSL_KEYSTORE_PASSWORD + " " +
              "parameter is empty.");
    }
    if (StringUtils.isEmpty(config.get(CommonConfigurationKeys.ZK_SSL_TRUSTSTORE_LOCATION))) {
      throw new IOException(
          "The SSL encryption is enabled for the component's ZooKeeper client connection, "
              + "however the " + CommonConfigurationKeys.ZK_SSL_TRUSTSTORE_LOCATION + " " +
              "parameter is empty.");
    }
    if (StringUtils.isEmpty(config.get(CommonConfigurationKeys.ZK_SSL_TRUSTSTORE_PASSWORD))) {
      throw new IOException(
          "The SSL encryption is enabled for the component's ZooKeeper client connection, "
              + "however the " + CommonConfigurationKeys.ZK_SSL_TRUSTSTORE_PASSWORD + "  " +
              "parameter is empty.");
    }
  }

  /**
   * Get ACLs for a ZNode.
   * @param path Path of the ZNode.
   * @return The list of ACLs.
   * @throws Exception If it cannot contact Zookeeper.
   */
  public List<ACL> getACL(final String path) throws Exception {
    return curator.getACL().forPath(path);
  }

  /**
   * Get the data in a ZNode.

View on GitHub (pinned to 2add963021)

Solutions

Set hadoop.zk.ssl.truststore.password (ideally via the Hadoop credential provider rather than plaintext XML)
If the alias lives in a JCEKS store, verify with hadoop credential list -provider ... that hadoop.zk.ssl.truststore.password exists there and hadoop.security.credential.provider.path is set
Re-check conf.get("hadoop.zk.ssl.truststore.password") in the failing JVM

Example fix

<!-- before: truststore.password missing while truststore.location set -->
<!-- after -->
<property>
  <name>hadoop.zk.ssl.truststore.password</name>
  <value>from-credential-provider-or-truststore-pass</value>
</property>

Defensive patterns

Strategy: validation

Validate before calling

String pw = conf.get("hadoop.zk.ssl.truststore.password");
if (pw == null || pw.isEmpty()) {
  throw new IllegalStateException("hadoop.zk.ssl.truststore.password is required when SSL is enabled");
}

Try / catch

try {
  zkManager.start(authInfos, true, null);
} catch (IOException e) {
  LOG.error("ZK SSL config incomplete: {}", e.getMessage());
  throw e;
}

Prevention

Provision all four SSL properties symmetrically; the last one is the most often forgotten
Use the credential provider for both passwords and test alias resolution before restart
Diff old vs new core-site.xml on TLS changes so trailing properties are not dropped

When it happens

Trigger: sslEnabled=true with hadoop.zk.ssl.truststore.password unset or empty; the password managed only on the server side; a credential provider path configured but the entry missing from the store.

Common situations: Rolling out ZooKeeper TLS where truststore passwords are provisioned inconsistently across nodes; secrets centralization projects that renamed the credential alias; config diffs where the trailing property of the SSL block was dropped.

Understand the failure class

SSL/TLS and certificate errors — how TLS handshakes and certificate validation fail.

Related errors

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