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

What it means

When start() runs with sslEnabled=true it calls validateSslConfiguration before building the Curator client. A ZooKeeper TLS client needs a local keystore, so hadoop.zk.ssl.keystore.location must be present and non-empty; a missing, blank, or whitespace-only value fails the StringUtils.isEmpty check and throws IOException.

Source

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

      validateSslConfiguration(conf);
    }
    CuratorFramework client = CuratorFrameworkFactory.builder().connectString(zkHostPort)
        .zookeeperFactory(
            new HadoopZookeeperFactory(conf.get(CommonConfigurationKeys.ZK_SERVER_PRINCIPAL),
                conf.get(CommonConfigurationKeys.ZK_KERBEROS_PRINCIPAL),
                conf.get(CommonConfigurationKeys.ZK_KERBEROS_KEYTAB), sslEnabled,
                new TruststoreKeystore(conf))).zkClientConfig(zkClientConfig)
        .sessionTimeoutMs(zkSessionTimeout).retryPolicy(retryPolicy)
        .authorization(authInfos).build();
    client.start();

    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(

View on GitHub (pinned to 2add963021)

Solutions

Set hadoop.zk.ssl.keystore.location to the absolute path of the client keystore (JKS/PKCS12) in core-site.xml
Verify exact key spelling and that the file exists and is readable by the service user
Confirm the key is visible in the failing process (log conf.get("hadoop.zk.ssl.keystore.location") or dump the Configuration)

Example fix

<!-- before -->
<property><name>hadoop.zk.ssl.enabled</name><value>true</value></property>
<!-- keystore.location missing -> IOException at start() -->

<!-- after -->
<property><name>hadoop.zk.ssl.enabled</name><value>true</value></property>
<property>
  <name>hadoop.zk.ssl.keystore.location</name>
  <value>/etc/security/zk/client.keystore.p12</value>
</property>

Defensive patterns

Strategy: validation

Validate before calling

String loc = conf.get("hadoop.zk.ssl.keystore.location");
if (loc == null || loc.trim().isEmpty()) {
  throw new IllegalStateException("hadoop.zk.ssl.keystore.location is required when SSL is enabled");
}
zkManager.start(authInfos, true, null);

Try / catch

try {
  zkManager.start(authInfos, true, null);
} catch (IOException e) {
  LOG.error("ZK SSL bootstrap failed ({}); verify the hadoop.zk.ssl.* properties", e.getMessage());
  throw e;
}

Prevention

Deploy the full hadoop.zk.ssl.* property set as one unit - enabling TLS half-configured always fails here
Smoke-test config completeness at service start with a pre-flight check of all four keys
Keep keystore files deployed alongside the configs that reference them

When it happens

Trigger: start(authInfos, true, ...) with hadoop.zk.ssl.keystore.location missing, declared as <value></value>, or whitespace-only; the key misspelled (e.g. hadoop.zk.ssl.keyStore.location); the config file defining it not loaded into the failing Configuration.

Common situations: Enabling ZooKeeper TLS when only server-side SSL was configured; templates declaring the property with an empty placeholder; environment-specific core-site.xml not shipped to the nodes.

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/1368ab1478612767. Report an issue: GitHub.