apple/pkl · error · ConnectException

errorConnectingToHost

errorConnectingToHost

Error message

errorConnectingToHost: ${host}

What it means

JdkHttpClient.send wraps java.net.ConnectException thrown by the JDK HttpClient, which otherwise has no message, into a ConnectException with code 'errorConnectingToHost' naming the target host. It means a TCP connection to the remote host could not be established.

Source

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

        java.net.http.HttpClient.newBuilder()
            .sslContext(createSslContext(certificateFiles, certificateBytes))
            .connectTimeout(connectTimeout)
            .proxy(proxySelector)
            .followRedirects(Redirect.NEVER)
            .build();
  }

  @Override
  public <T> HttpResponse<T> send(
      HttpRequest request,
      BodyHandler<T> responseBodyHandler,
      HttpRequestChecker httpRequestChecker)
      throws IOException {
    try {
      return underlying.send(request, responseBodyHandler);
    } catch (ConnectException e) {
      // original exception has no message
      throw new ConnectException(
          ErrorMessages.create("errorConnectingToHost", request.uri().getHost()));
    } catch (SSLHandshakeException e) {
      throw new SSLHandshakeException(
          ErrorMessages.create(
              "errorSslHandshake", request.uri().getHost(), Exceptions.getRootReason(e)));
    } catch (SSLException e) {
      throw new SSLException(Exceptions.getRootReason(e));
    } catch (InterruptedException e) {
      // next best thing after letting (checked) InterruptedException bubble up
      Thread.currentThread().interrupt();
      throw new IOException(e);
    }
  }

  @Override
  public void close() {
    try {
      closeMethod.invoke(underlying);

View on GitHub (pinned to f3efcbfc9b)

Solutions

1. Verify the host is reachable: ping/curl the exact URL from the same machine
2. Check DNS resolution and that the port is open (e.g. `nc -vz host port`)
3. Fix proxy settings if traffic must go through a proxy (Pkl proxy settings)
4. Start the local service if connecting to localhost, or correct the hostname/port typo
5. Check firewall/VPN/network rules blocking the outbound connection

Example fix

// before
baseUri = "https://locallhost:8090"
// after (typo fixed & service started)
baseUri = "https://localhost:8090"

// pre-flight connectivity check before evaluation
var host = URI.create(baseUri).getHost();
var reachable = new Socket().let(s -> { try { s.connect(new InetSocketAddress(host, port), 3000); return true; } catch (IOException e) { return false; } });
if (!reachable) throw new IllegalStateException("Cannot reach " + host + "; check network/proxy");

try {
  return client.send(request, handler);
} catch (ConnectException e) {
  if (e.getMessage().startsWith("errorConnectingToHost")) {
    // exponential backoff retry, or fail with guidance about host reachability/proxy
  }
}

When it happens

Trigger: Any HTTP(S) request via the Pkl JDK HTTP client where the TCP connect fails: host unreachable, port closed, DNS resolving but nothing listening, firewall dropping, or localhost service not started.

Common situations: Project imports from an unreachable registry, HTTPS proxies misconfigured, offline environment/VPN down, typo in hostname or port, service bound to a different interface.

Understand the failure class

Background: ECONNREFUSED and "connection refused" / "could not connect to server" errors: what they mean and how to fix them — this error's family across 44 libraries.

Related errors

• ioErrorMakingHttpGet
• httpTooManyRedirects
• httpRedirectNoLocation
• invalidDependencyMetadata
• badHttpStatusCode

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