apple/pkl · error · HttpClientException

cannotFindCertFile

cannotFindCertFile

Error message

cannotFindCertFile: ${file}

What it means

Pkl's HTTP client was asked to use TLS certificates from a file path that does not exist. The client gathers certificates during construction of the HTTP session and throws HttpClientException wrapped around this error when a configured certificate file cannot be found on disk. It is a configuration/resource error, not a network error.

Source

Thrown at pkl-core/src/main/java/org/pkl/core/http/JdkHttpClient.java:162

      var sslContext = SSLContext.getInstance("TLS");
      sslContext.init(null, trustManagerFactory.getTrustManagers(), new SecureRandom());

      return sslContext;
    } catch (GeneralSecurityException | IOException e) {
      throw new HttpClientException(
          ErrorMessages.create("cannotInitHttpClient", Exceptions.getRootReason(e)), e);
    }
  }

  private static List<Certificate> gatherCertificates(
      CertificateFactory factory, List<Path> certificateFiles, List<ByteBuffer> certificateBytes) {
    var certificates = new ArrayList<Certificate>();
    for (var file : certificateFiles) {
      try (var stream = Files.newInputStream(file)) {
        collectCertificates(certificates, factory, stream, file);
      } catch (NoSuchFileException e) {
        throw new HttpClientException(ErrorMessages.create("cannotFindCertFile", file));
      } catch (IOException e) {
        throw new HttpClientException(
            ErrorMessages.create("cannotReadCertFile", Exceptions.getRootReason(e)));
      }
    }
    for (var byteBuffer : certificateBytes) {
      var stream = new ByteArrayInputStream(byteBuffer.array());
      collectCertificates(certificates, factory, stream, "<unavailable>");
    }
    return certificates;
  }

  private static void collectCertificates(
      ArrayList<Certificate> anchors,
      CertificateFactory factory,
      InputStream stream,
      Object source) {
    var input = new PushbackInputStream(stream);

View on GitHub (pinned to f3efcbfc9b)

Solutions

  1. Verify the certificate file path exists (e.g. `ls -l <path>`) and fix the path in the Pkl HTTP configuration.
  2. Use an absolute path to avoid surprises from the process working directory.
  3. If the cert comes from a package/system bundle (e.g. /etc/ssl/certs/ca-certificates.crt), install the CA certificate package in the environment.
  4. If certificates are provided as bytes instead, use the certificate-bytes option so no file lookup occurs.

Example fix

// before (pkl)
http {
  proxy { address = ...; certificateFile = "/etc/ssl/certs/my-ca.pem" } // file missing
}
// after (pkl)
http {
  proxy { address = ...; certificateFile = "/etc/ssl/certs/ca-certificates.crt" } // verified existing
}
Defensive patterns

Strategy: validation

Validate before calling

Path certFile = Paths.get("/etc/ssl/certs/custom-ca.pem");
if (!Files.isRegularFile(certFile)) {
  throw new IllegalStateException("Certificate file missing: " + certFile);
}
if (!Files.isReadable(certFile)) {
  throw new IllegalStateException("Certificate file not readable: " + certFile);
}

Try / catch

try {
  // run Pkl / build the HTTP client
} catch (HttpClientException e) {
  if (e.getMessage().startsWith("cannotFindCertFile")) {
    // fall back to default trust store or fix the path
  }
}

Prevention

When it happens

Trigger: Passing a certificate file path via HTTP client configuration options (e.g. certificateFiles for an HTTP proxy or external module) where the path does not exist on disk; Files.newInputStream throws NoSuchFileException in gatherCertificates (called from certs) and Pkl maps it to cannotFindCertFile.

Common situations: Typo in a cert path in project config, running Pkl on a machine or container where the cert bundle was never installed, relative path resolved against an unexpected working directory, or certs deleted after configuration was written.

Understand the failure class

Background: "File not found" and ENOENT errors: why libraries can't find a file that should exist — this error's family across 50 libraries.

Related errors

AI-assisted analysis of apple/pkl@f3efcbfc9b (2026-09-08). Data as JSON: /api/errors/4c2c95018bce0499. Report an issue: GitHub.