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

What it means

validateSslConfiguration next requires hadoop.zk.ssl.keystore.password, the password protecting the keystore whose location was just checked. A missing or empty value throws IOException with this message before any connection attempt, so the failure is configuration, not network.

Source

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

                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(
          "The SSL encryption is enabled for the component's ZooKeeper client connection, "
              + "however the " + CommonConfigurationKeys.ZK_SSL_TRUSTSTORE_PASSWORD + "  " +
              "parameter is empty.");
    }
  }

View on GitHub (pinned to 2add963021)

Solutions

Set hadoop.zk.ssl.keystore.password in core-site.xml
Better: keep it out of XML with the Hadoop credential provider (hadoop credential create hadoop.zk.ssl.keystore.password -provider jceks://file/..., plus hadoop.security.credential.provider.path) - Configuration resolves it transparently
Re-check conf.get("hadoop.zk.ssl.keystore.password") in the failing JVM

Example fix

<!-- before: password key missing while sslEnabled=true -->
<!-- after -->
<property>
  <name>hadoop.zk.ssl.keystore.password</name>
  <value>from-credential-provider-or-keystore-pass</value>
</property>
<!-- preferred: hadoop credential create hadoop.zk.ssl.keystore.password -provider jceks://file/etc/security/zk/secrets.jceks -->

Defensive patterns

Strategy: validation

Validate before calling

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

Try / catch

try {
  zkManager.start(authInfos, true, null);
} catch (IOException e) {
  if (e.getMessage().contains("keystore.password")) {
    // config problem, not connectivity: fail with actionable text
    throw new ServiceConfigurationException(e.getMessage(), e);
  }
  throw e;
}

Prevention

Keep SSL secrets in the Hadoop credential provider (JCEKS) instead of XML
Verify credential aliases with hadoop credential list before rollout
Never leave placeholder values like CHANGEIT in templates that gate startup checks

When it happens

Trigger: sslEnabled=true with hadoop.zk.ssl.keystore.password unset or empty; the password stored only under a differently spelled key; an XML quoting/CDATA mistake leaving the value blank.

Common situations: Enabling ZooKeeper TLS where the runbook documents the keystore but not its password key; secrets moved to a vault or credential provider that is not wired into Configuration; values copied from documentation with stray quotes or whitespace.

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/6fd9438e1a004304. Report an issue: GitHub.