{"record":{"id":"678c06ccc56fe170","repo":"apache/hadoop","slug":"unknown-server-chain-certificate","errorCode":null,"errorMessage":"Unknown server chain certificate: {}","messagePattern":"Unknown server chain certificate: (.+?)","errorType":"exception","errorClass":"CertificateException","httpStatus":null,"severity":"error","filePath":"hadoop-common-project/hadoop-common/src/main/java/org/apache/hadoop/security/ssl/ReloadingX509TrustManager.java","lineNumber":99,"sourceCode":"  public void checkClientTrusted(X509Certificate[] chain, String authType)\n    throws CertificateException {\n    X509TrustManager tm = trustManagerRef.get();\n    if (tm != null) {\n      tm.checkClientTrusted(chain, authType);\n    } else {\n      throw new CertificateException(\"Unknown client chain certificate: \" +\n                                     chain[0].toString());\n    }\n  }\n\n  @Override\n  public void checkServerTrusted(X509Certificate[] chain, String authType)\n    throws CertificateException {\n    X509TrustManager tm = trustManagerRef.get();\n    if (tm != null) {\n      tm.checkServerTrusted(chain, authType);\n    } else {\n      throw new CertificateException(\"Unknown server chain certificate: \" +\n                                     chain[0].toString());\n    }\n  }\n\n  private static final X509Certificate[] EMPTY = new X509Certificate[0];\n  @Override\n  public X509Certificate[] getAcceptedIssuers() {\n    X509Certificate[] issuers = EMPTY;\n    X509TrustManager tm = trustManagerRef.get();\n    if (tm != null) {\n      issuers = tm.getAcceptedIssuers();\n    }\n    return issuers;\n  }\n\n  public ReloadingX509TrustManager loadFrom(Path path) {\n    try {\n      this.trustManagerRef.set(loadTrustManager(path));","sourceCodeStart":81,"sourceCodeEnd":117,"githubUrl":"https://github.com/apache/hadoop/blob/2add9630210752f88ceb1bb74eb65e37bf41da8e/hadoop-common-project/hadoop-common/src/main/java/org/apache/hadoop/security/ssl/ReloadingX509TrustManager.java#L81-L117","documentation":"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.","triggerScenarios":"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).","commonSituations":"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.","solutions":["Verify the truststore loads standalone: `keytool -list -keystore <file> -storepass <pw>`","Correct ssl.client.truststore.location / .password / .type in the client's SSL configuration file","Ensure the client process can read the file (permissions, container mounts)","Restart the client JVM after fixing so the trust manager initializes cleanly"],"exampleFix":"# before: truststore replaced by a partial copy during rotation\n\n# after: deploy atomically, then verify\ncp new.jks /etc/security/tls/truststore.jks.new\nkeytool -list -keystore /etc/security/tls/truststore.jks.new -storepass $PW\nmv /etc/security/tls/truststore.jks.new /etc/security/tls/truststore.jks","handlingStrategy":"try-catch","validationCode":"// client preflight: verify the truststore loads before first use\nKeyStore ks = KeyStore.getInstance(truststoreType);\ntry (InputStream in = Files.newInputStream(Paths.get(truststoreLocation))) {\n  ks.load(in, truststorePassword.toCharArray());\n}","typeGuard":null,"tryCatchPattern":"try {\n  connection.getResponseCode();\n} catch (SSLHandshakeException e) {\n  if (e.getMessage() != null && e.getMessage().contains(\"Unknown server chain certificate\")) {\n    // local trust material problem, not an untrusted server: fix ssl.client.truststore.*\n    LOG.error(\"Client trust manager unavailable; check truststore config\", e);\n  }\n  throw e;\n}","preventionTips":["Distribute the correct truststore with the client and verify it loads in deployment checks","Use atomic file replacement during truststore rotation","Watch client logs for reload failure messages after certificate rotations"],"tags":["ssl","tls","truststore","certificate","handshake","hadoop","client"],"backgroundTag":"truststore-unavailable","analyzedSha":"2add9630210752f88ceb1bb74eb65e37bf41da8e","analyzedAt":"2026-08-22T19:55:07.957Z","schemaVersion":2},"datasetVersion":"2026-08-23T01:17:44.959Z"}