{"record":{"id":"93e794b514e82b0a","repo":"apple/pkl","slug":"errorconnectingtohost","errorCode":"errorConnectingToHost","errorMessage":"errorConnectingToHost: ${host}","messagePattern":"errorConnectingToHost: (.+?)","errorType":"exception","errorClass":"ConnectException","httpStatus":null,"severity":"error","filePath":"pkl-core/src/main/java/org/pkl/core/http/JdkHttpClient.java","lineNumber":100,"sourceCode":"        java.net.http.HttpClient.newBuilder()\n            .sslContext(createSslContext(certificateFiles, certificateBytes))\n            .connectTimeout(connectTimeout)\n            .proxy(proxySelector)\n            .followRedirects(Redirect.NEVER)\n            .build();\n  }\n\n  @Override\n  public <T> HttpResponse<T> send(\n      HttpRequest request,\n      BodyHandler<T> responseBodyHandler,\n      HttpRequestChecker httpRequestChecker)\n      throws IOException {\n    try {\n      return underlying.send(request, responseBodyHandler);\n    } catch (ConnectException e) {\n      // original exception has no message\n      throw new ConnectException(\n          ErrorMessages.create(\"errorConnectingToHost\", request.uri().getHost()));\n    } catch (SSLHandshakeException e) {\n      throw new SSLHandshakeException(\n          ErrorMessages.create(\n              \"errorSslHandshake\", request.uri().getHost(), Exceptions.getRootReason(e)));\n    } catch (SSLException e) {\n      throw new SSLException(Exceptions.getRootReason(e));\n    } catch (InterruptedException e) {\n      // next best thing after letting (checked) InterruptedException bubble up\n      Thread.currentThread().interrupt();\n      throw new IOException(e);\n    }\n  }\n\n  @Override\n  public void close() {\n    try {\n      closeMethod.invoke(underlying);","sourceCodeStart":82,"sourceCodeEnd":118,"githubUrl":"https://github.com/apple/pkl/blob/f3efcbfc9b60d30053b0536d664948d7aa1b8673/pkl-core/src/main/java/org/pkl/core/http/JdkHttpClient.java#L82-L118","documentation":"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.","triggerScenarios":"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.","commonSituations":"Project imports from an unreachable registry, HTTPS proxies misconfigured, offline environment/VPN down, typo in hostname or port, service bound to a different interface.","solutions":["Verify the host is reachable: ping/curl the exact URL from the same machine","Check DNS resolution and that the port is open (e.g. `nc -vz host port`)","Fix proxy settings if traffic must go through a proxy (Pkl proxy settings)","Start the local service if connecting to localhost, or correct the hostname/port typo","Check firewall/VPN/network rules blocking the outbound connection"],"exampleFix":"// before\nbaseUri = \"https://locallhost:8090\"\n// after (typo fixed & service started)\nbaseUri = \"https://localhost:8090\"","handlingStrategy":"retry","validationCode":"// pre-flight connectivity check before evaluation\nvar host = URI.create(baseUri).getHost();\nvar reachable = new Socket().let(s -> { try { s.connect(new InetSocketAddress(host, port), 3000); return true; } catch (IOException e) { return false; } });\nif (!reachable) throw new IllegalStateException(\"Cannot reach \" + host + \"; check network/proxy\");","typeGuard":null,"tryCatchPattern":"try {\n  return client.send(request, handler);\n} catch (ConnectException e) {\n  if (e.getMessage().startsWith(\"errorConnectingToHost\")) {\n    // exponential backoff retry, or fail with guidance about host reachability/proxy\n  }\n}","preventionTips":["Curl/ping target hosts in deployment health checks before running evaluations","Verify proxy configuration (Pkl proxy settings, HTTP_PROXY) in restricted networks","Check DNS resolution for the hosts your project imports from","Retry transient network failures with exponential backoff"],"tags":["network","http","connection","pkl"],"backgroundTag":"connection-refused","analyzedSha":"f3efcbfc9b60d30053b0536d664948d7aa1b8673","analyzedAt":"2026-09-08T13:10:45.570Z","contentChangedAt":"2026-09-08T13:10:45.570Z","schemaVersion":2},"datasetVersion":"2026-09-14T11:17:12.474Z"}