apache/hadoop · error · GeneralSecurityException

The property '{}' has not been set in the ssl configuration

Error message

The property '{}' has not been set in the ssl configuration file.

What it means

FileBasedKeyStoresFactory requires the keystore location property in the SSL configuration file; the key is resolved from the template ssl.<mode>.keystore.location, i.e. ssl.server.keystore.location or ssl.client.keystore.location in the file referenced by hadoop.ssl.server.conf / hadoop.ssl.client.conf (ssl-server.xml / ssl-client.xml by default). If the value is empty, init fails with this GeneralSecurityException.

Source

Thrown at hadoop-common-project/hadoop-common/src/main/java/org/apache/hadoop/security/ssl/FileBasedKeyStoresFactory.java:167

    trustManagers = new TrustManager[]{trustManager};
  }

  /**
   * Implements logic of initializing the KeyManagers with the options
   * to reload keystores.
   * @param mode client or server
   * @param keystoreType The keystore type.
   * @param storesReloadInterval The interval to check if the keystore certificates
   *                             file has changed.
   */
  private void createKeyManagersFromConfiguration(SSLFactory.Mode mode,
                                                  String keystoreType, long storesReloadInterval)
      throws GeneralSecurityException, IOException {
    String locationProperty =
        resolvePropertyName(mode, SSL_KEYSTORE_LOCATION_TPL_KEY);
    String keystoreLocation = conf.get(locationProperty, "");
    if (keystoreLocation.isEmpty()) {
      throw new GeneralSecurityException("The property '" + locationProperty +
          "' has not been set in the ssl configuration file.");
    }
    String passwordProperty =
        resolvePropertyName(mode, SSL_KEYSTORE_PASSWORD_TPL_KEY);
    String keystorePassword = getPassword(conf, passwordProperty, "");
    if (keystorePassword.isEmpty()) {
      throw new GeneralSecurityException("The property '" + passwordProperty +
          "' has not been set in the ssl configuration file.");
    }
    String keyPasswordProperty =
        resolvePropertyName(mode, SSL_KEYSTORE_KEYPASSWORD_TPL_KEY);
    // Key password defaults to the same value as store password for
    // compatibility with legacy configurations that did not use a separate
    // configuration property for key password.
    String keystoreKeyPassword = getPassword(
        conf, keyPasswordProperty, keystorePassword);
    if (LOG.isDebugEnabled()) {
      LOG.debug(mode.toString() + " KeyStore: " + keystoreLocation);

View on GitHub (pinned to 2add963021)

Solutions

Set <name>ssl.server.keystore.location</name> (or ssl.client.keystore.location) in the ssl-server.xml/ssl-client.xml referenced by hadoop.ssl.server.conf/hadoop.ssl.client.conf
Verify the referenced file is actually the one being loaded: check the hadoop.ssl.*.conf property in core-site.xml and the file on the server's classpath
Confirm the path exists and is readable by the service user
If the password comes from a CredentialProvider, make sure the location property itself is still set literally; only the password may be indirected

Example fix

<!-- ssl-server.xml: before -->
<!-- ssl.server.keystore.location missing -->

<!-- after -->
<property>
  <name>ssl.server.keystore.location</name>
  <value>/etc/security/tls/keystore.jks</value>
</property>

Defensive patterns

Strategy: validation

Validate before calling

String key = "ssl." + (isServer ? "server" : "client") + ".keystore.location";
String location = sslConf.get(key, "");
if (location.isEmpty() || !new File(location).canRead()) {
  throw new IllegalStateException(key + " missing or unreadable: " + location);
}
SSLFactory factory = new SSLFactory(mode, conf);

Try / catch

try {
  factory = new SSLFactory(SSLFactory.Mode.SERVER, conf);
} catch (GeneralSecurityException e) {
  if (e.getMessage().contains("has not been set in the ssl configuration file")) {
    // fail startup with a precise ops message naming the missing property
    throw new IllegalStateException("TLS config incomplete: " + e.getMessage(), e);
  }
  throw e;
}

Prevention

Add config smoke tests that assert all required ssl.*.keystore/truststore properties before deploy
Template ssl-server.xml in config management and alert when keys are removed
Confirm hadoop.ssl.server.conf / hadoop.ssl.client.conf point at the intended files on every host

When it happens

Trigger: Creating an SSLFactory(Mode.SERVER, conf) (or a service that does: HTTPS HDFS, HttpFS, KMS, YARN timelineserver) where ssl-server.xml lacks ssl.server.keystore.location; pointing hadoop.ssl.server.conf at the wrong file; a typo'd property name.

Common situations: Enabling https.xml property (JCEKS password files need the CredentialProvider API so the raw property is non-empty); wrong conf variable (client vs server) after refactors.

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/59a952ce2dc75189. Report an issue: GitHub.