apache/hadoop · error · CertificateException

Unknown server chain certificate: {}

Error message

Unknown server chain certificate: {}

What it means

ReloadingX509TrustManager.checkServerTrusted throws CertificateException when trustManagerRef is null, so the client cannot validate the server's certificate chain (chain[0] is echoed). As with the client variant, this means no trust manager is loaded at all — missing trust material — rather than an untrusted certificate per se.

Source

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

  public void checkClientTrusted(X509Certificate[] chain, String authType)
    throws CertificateException {
    X509TrustManager tm = trustManagerRef.get();
    if (tm != null) {
      tm.checkClientTrusted(chain, authType);
    } else {
      throw new CertificateException("Unknown client chain certificate: " +
                                     chain[0].toString());
    }
  }

  @Override
  public void checkServerTrusted(X509Certificate[] chain, String authType)
    throws CertificateException {
    X509TrustManager tm = trustManagerRef.get();
    if (tm != null) {
      tm.checkServerTrusted(chain, authType);
    } else {
      throw new CertificateException("Unknown server chain certificate: " +
                                     chain[0].toString());
    }
  }

  private static final X509Certificate[] EMPTY = new X509Certificate[0];
  @Override
  public X509Certificate[] getAcceptedIssuers() {
    X509Certificate[] issuers = EMPTY;
    X509TrustManager tm = trustManagerRef.get();
    if (tm != null) {
      issuers = tm.getAcceptedIssuers();
    }
    return issuers;
  }

  public ReloadingX509TrustManager loadFrom(Path path) {
    try {
      this.trustManagerRef.set(loadTrustManager(path));

View on GitHub (pinned to 2add963021)

Solutions

  1. Verify the truststore loads standalone: `keytool -list -keystore <file> -storepass <pw>`
  2. Correct ssl.client.truststore.location / .password / .type in the client's SSL configuration file
  3. Ensure the client process can read the file (permissions, container mounts)
  4. Restart the client JVM after fixing so the trust manager initializes cleanly

Example fix

# before: truststore replaced by a partial copy during rotation

# after: deploy atomically, then verify
cp new.jks /etc/security/tls/truststore.jks.new
keytool -list -keystore /etc/security/tls/truststore.jks.new -storepass $PW
mv /etc/security/tls/truststore.jks.new /etc/security/tls/truststore.jks
Defensive patterns

Strategy: try-catch

Validate before calling

// client preflight: verify the truststore loads before first use
KeyStore ks = KeyStore.getInstance(truststoreType);
try (InputStream in = Files.newInputStream(Paths.get(truststoreLocation))) {
  ks.load(in, truststorePassword.toCharArray());
}

Try / catch

try {
  connection.getResponseCode();
} catch (SSLHandshakeException e) {
  if (e.getMessage() != null && e.getMessage().contains("Unknown server chain certificate")) {
    // local trust material problem, not an untrusted server: fix ssl.client.truststore.*
    LOG.error("Client trust manager unavailable; check truststore config", e);
  }
  throw e;
}

Prevention

When it happens

Trigger: A client TLS handshake through an SSLFactory/ReloadingX509TrustManager whose truststore never loaded or whose reload left no usable trust manager (file corrupt, wrong password/type, unreadable path).

Common situations: Clients (WebHDFS https, KMS client, ABFS/HDFS over TLS) after truststore rotation left a truncated file; truststore password changed but client ssl-client.xml not updated; permissions denying the client user read access.

Understand the failure class

Related errors

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