{"record":{"id":"547e6dad22d28fce","repo":"apple/pkl","slug":"cannotinithttpclient","errorCode":"cannotInitHttpClient","errorMessage":"cannotInitHttpClient: ${reason}","messagePattern":"cannotInitHttpClient: (.+?)","errorType":"exception","errorClass":"HttpClientException","httpStatus":null,"severity":"error","filePath":"pkl-core/src/main/java/org/pkl/core/http/JdkHttpClient.java","lineNumber":150,"sourceCode":"        return SSLContext.getDefault();\n      }\n\n      var certFactory = CertificateFactory.getInstance(\"X.509\");\n      List<Certificate> certs = gatherCertificates(certFactory, certificateFiles, certificateBytes);\n      var keystore = KeyStore.getInstance(KeyStore.getDefaultType());\n      keystore.load(null);\n      for (var i = 0; i < certs.size(); i++) {\n        keystore.setCertificateEntry(\"Certificate\" + i, certs.get(i));\n      }\n      var trustManagerFactory = TrustManagerFactory.getInstance(\"PKIX\");\n      trustManagerFactory.init(keystore);\n\n      var sslContext = SSLContext.getInstance(\"TLS\");\n      sslContext.init(null, trustManagerFactory.getTrustManagers(), new SecureRandom());\n\n      return sslContext;\n    } catch (GeneralSecurityException | IOException e) {\n      throw new HttpClientException(\n          ErrorMessages.create(\"cannotInitHttpClient\", Exceptions.getRootReason(e)), e);\n    }\n  }\n\n  private static List<Certificate> gatherCertificates(\n      CertificateFactory factory, List<Path> certificateFiles, List<ByteBuffer> certificateBytes) {\n    var certificates = new ArrayList<Certificate>();\n    for (var file : certificateFiles) {\n      try (var stream = Files.newInputStream(file)) {\n        collectCertificates(certificates, factory, stream, file);\n      } catch (NoSuchFileException e) {\n        throw new HttpClientException(ErrorMessages.create(\"cannotFindCertFile\", file));\n      } catch (IOException e) {\n        throw new HttpClientException(\n            ErrorMessages.create(\"cannotReadCertFile\", Exceptions.getRootReason(e)));\n      }\n    }\n    for (var byteBuffer : certificateBytes) {","sourceCodeStart":132,"sourceCodeEnd":168,"githubUrl":"https://github.com/apple/pkl/blob/f3efcbfc9b60d30053b0536d664948d7aa1b8673/pkl-core/src/main/java/org/pkl/core/http/JdkHttpClient.java#L132-L168","documentation":"createSslContext builds the SSLContext used by the JDK HTTP client from configured trusted certificates. If gathering certificates or initializing SSLContext fails (GeneralSecurityException or IOException), it throws HttpClientException with code 'cannotInitHttpClient' carrying the root reason. The HTTP client cannot be constructed at all.","triggerScenarios":"Passing certificateFiles/certificateBytes that don't exist, are unreadable, or aren't valid X.509/PKCS formats, or a JVM security-provider failure during SSLContext.getInstance(\"TLS\")/init.","commonSituations":"Typo in certificate file path, PEM vs DER format confusion, corrupt certificate files, missing crypto providers in stripped-down JREs, permission issues reading cert files.","solutions":["Check the root reason in the message: fix the specific certificate path/format problem","Verify each certificate file exists, is readable, and is a valid PEM/DER X.509 cert (openssl x509 -in file -noout)","Regenerate or re-export the certificate in a supported format","Ensure the JVM has the TLS security providers available (full JDK, not a stripped runtime)"],"exampleFix":"// before\nsettings.setCertificateFiles(List.of(Path.of(\"/etc/certs/ca.pem.txt\"))); // wrong file\n// after\nsettings.setCertificateFiles(List.of(Path.of(\"/etc/certs/internal-ca.pem\")));","handlingStrategy":"validation","validationCode":"void validateCertificates(List<Path> files) throws IOException {\n  for (Path f : files) {\n    if (!Files.isRegularFile(f) || !Files.isReadable(f))\n      throw new IOException(\"Certificate file missing or unreadable: \" + f);\n    // optional: parse to confirm valid X.509\n    CertificateFactory.getInstance(\"X.509\").generateCertificate(Files.newInputStream(f));\n  }\n}","typeGuard":null,"tryCatchPattern":"try {\n  var client = JdkHttpClient.create(settings); // triggers createSslContext\n} catch (HttpClientException e) {\n  if (e.getMessage().startsWith(\"cannotInitHttpClient\")) {\n    // inspect root reason; fix certificate paths/formats or JVM security providers\n  }\n}","preventionTips":["Validate certificate file paths and formats (PEM/DER X.509) at config-load time","Deploy on a full JDK so TLS security providers are present","Keep trusted CA bundles updated alongside your config","Log certificate file locations at startup to speed up path debugging"],"tags":["ssl","http-client","certificate","initialization"],"backgroundTag":"http-client-init-failed","analyzedSha":"f3efcbfc9b60d30053b0536d664948d7aa1b8673","analyzedAt":"2026-09-08T13:10:45.570Z","contentChangedAt":"2026-09-08T13:10:45.570Z","schemaVersion":2},"datasetVersion":"2026-09-17T15:17:12.973Z"}