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.location parameter is empty.

What it means

The third check in validateSslConfiguration requires hadoop.zk.ssl.truststore.location, the truststore holding the CA/server certificates the client uses to validate the ZooKeeper server. A missing or empty value throws IOException before the client starts, even if the keystore settings are complete.

Source

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

    this.curator = client;
  }
  /* Check on SSL/TLS client connection requirements to emit the name of the
   configuration missing. It improves supportability. */
  private void validateSslConfiguration(Configuration config) throws IOException {
    if (StringUtils.isEmpty(config.get(CommonConfigurationKeys.ZK_SSL_KEYSTORE_LOCATION))) {
      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.
   */

View on GitHub (pinned to 2add963021)

Solutions

Set hadoop.zk.ssl.truststore.location to the truststore path (commonly JKS containing the cluster CA) in core-site.xml
Deploy the truststore file to every node running the ZooKeeper client component and make it readable by the service user
Verify with conf.get("hadoop.zk.ssl.truststore.location") that the key resolves in the failing process

Example fix

<!-- before -->
<property><name>hadoop.zk.ssl.keystore.location</name><value>/etc/security/zk/client.p12</value></property>
<!-- truststore.location missing -> IOException at start() -->

<!-- after: add -->
<property>
  <name>hadoop.zk.ssl.truststore.location</name>
  <value>/etc/security/zk/truststore.jks</value>
</property>

Defensive patterns

Strategy: validation

Validate before calling

String ts = conf.get("hadoop.zk.ssl.truststore.location");
if (ts == null || ts.trim().isEmpty()) {
  throw new IllegalStateException("hadoop.zk.ssl.truststore.location 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

Distribute the cluster CA truststore to client nodes as part of TLS rollout
Do not assume JVM default cacerts - this API requires the explicit property
Pair every keystore deploy with its truststore in the same config change

When it happens

Trigger: sslEnabled=true with hadoop.zk.ssl.truststore.location unset, empty, or misspelled; keystore configured but the cluster CA was only ever distributed to servers; truststore path pointing to a file not deployed on this node.

Common situations: Client-side TLS configured with a keystore but no truststore; teams assuming the JVM cacerts default applies - this API requires an explicit truststore; per-environment configs where only one env got the truststore path.

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/025f6c3632d76dc5. Report an issue: GitHub.