{"record":{"id":"12b5cc21be9837f9","repo":"apache/hadoop","slug":"unknown-client-chain-certificate","errorCode":null,"errorMessage":"Unknown client chain certificate: {}","messagePattern":"Unknown client 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":87,"sourceCode":"   * @throws GeneralSecurityException thrown if the truststore could not be\n   * initialized due to a security error.\n   */\n  public ReloadingX509TrustManager(String type, String location, String password)\n    throws IOException, GeneralSecurityException {\n    this.type = type;\n    this.password = password;\n    trustManagerRef = new AtomicReference<X509TrustManager>();\n    trustManagerRef.set(loadTrustManager(Paths.get(location)));\n  }\n\n  @Override\n  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","sourceCodeStart":69,"sourceCodeEnd":105,"githubUrl":"https://github.com/apache/hadoop/blob/2add9630210752f88ceb1bb74eb65e37bf41da8e/hadoop-common-project/hadoop-common/src/main/java/org/apache/hadoop/security/ssl/ReloadingX509TrustManager.java#L69-L105","documentation":"ReloadingX509TrustManager.checkClientTrusted throws CertificateException when its internal trustManagerRef is null, i.e. there is no loaded X509TrustManager to validate the client's certificate chain (chain[0] is echoed in the message). This is a server-side state failure: the reloadable trust manager could not supply trust material at handshake time, not a normal certificate rejection.","triggerScenarios":"A server-side TLS handshake (HDFS DataNode/NameNode HTTPS, KMS, etc. using FileBasedKeyStoresFactory with a reloadable truststore) while the underlying trust manager failed to load or was left absent — for example truststore file missing/corrupt at startup in code paths that continue, or a failed reload in versions that null the reference.","commonSituations":"Truststore path typo so the file never loads; truststore replaced with a corrupt/truncated file during certificate rotation; type mismatch (PKCS12 file configured as jks).","solutions":["Validate the truststore out of band: `keytool -list -keystore <truststore> -storetype <type>` with the configured password","Fix ssl.<mode>.truststore.location / .type / .password in the SSL configuration so the initial load succeeds","Check the service log for the companion 'Could not load truststore (keep using existing one)' message to find the underlying load failure","Restart the service after repairing the truststore so a valid trust manager is installed"],"exampleFix":"# before: ssl-server.xml\nssl.server.truststore.type=jks   # file is actually PKCS12\n\n# after\nssl.server.truststore.type=PKCS12\n# verify with: keytool -list -keystore truststore.p12 -storetype PKCS12","handlingStrategy":"try-catch","validationCode":"// startup check: truststore must load before the TLS listener is opened\nKeyStore ks = KeyStore.getInstance(conf.get(\"ssl.server.truststore.type\", \"jks\"));\ntry (InputStream in = Files.newInputStream(Paths.get(location))) {\n  ks.load(in, password.toCharArray());\n}\nLOG.info(\"Truststore {} verified\", location);","typeGuard":null,"tryCatchPattern":"try {\n  serverSocket.accept(); // handshake validation\n} catch (SSLHandshakeException e) {\n  if (e.getMessage().contains(\"Unknown client chain certificate\")) {\n    // trust material unavailable on our side: check truststore load logs, fix config, restart\n    LOG.error(\"Trust manager not loaded; verify ssl.server.truststore.* settings\", e);\n  }\n  throw e;\n}","preventionTips":["Validate truststores with keytool before configuring and at every rotation","Alert on 'Could not load truststore' log lines so failed reloads are noticed before handshakes fail","Keep truststore type, location, and password consistent across environments"],"tags":["ssl","tls","truststore","certificate","handshake","hadoop"],"backgroundTag":"truststore-unavailable","analyzedSha":"2add9630210752f88ceb1bb74eb65e37bf41da8e","analyzedAt":"2026-08-22T19:55:07.957Z","schemaVersion":2},"datasetVersion":"2026-08-23T01:17:44.959Z"}