apple/pkl · error · PackageLoadError

ioErrorMakingHttpGet

ioErrorMakingHttpGet

Error message

ioErrorMakingHttpGet

What it means

The HTTP client failed at the I/O level while downloading a package resource from an external URI, so Pkl throws PackageLoadError ioErrorMakingHttpGet. Unlike badHttpStatusCode (a non-200 response), this indicates the request itself could not be completed — connection failure, DNS failure, TLS error, timeout, or connection reset.

Source

Thrown at pkl-core/src/main/java/org/pkl/core/packages/PackageResolvers.java:209

            requestUri);
      }
    }

    protected InputStream openExternalUri(URI uri) throws SecurityManagerException {
      if (!HttpUtils.isHttpUrl(uri)) {
        throw new IllegalArgumentException("Expected HTTP(S) URL, but got: " + uri);
      }

      // treat package assets as resources instead of modules
      securityManager.checkReadResource(uri);
      var request = HttpRequest.newBuilder(uri).build();
      HttpResponse<InputStream> response;
      try {
        response =
            httpClient.send(
                request, BodyHandlers.ofInputStream(), securityManager::checkReadResource);
      } catch (IOException e) {
        throw new PackageLoadError(e, "ioErrorMakingHttpGet", uri, e.getMessage());
      }
      try {
        HttpUtils.checkHasStatusCode200(response);
      } catch (IOException e) {
        throw new PackageLoadError("badHttpStatusCode", response.statusCode(), response.uri());
      }
      return response.body();
    }

    protected IOException fileIsADirectory() {
      // Sync with error message from `Files#readString(Path)`
      return new IOException("Is a directory");
    }

    protected abstract DependencyMetadata doGetDependencyMetadata(
        PackageUri packageUri, @Nullable Checksums checksums)
        throws IOException, SecurityManagerException;

View on GitHub (pinned to f3efcbfc9b)

Solutions

1. Check basic connectivity: curl -v the URL from the error to reproduce the failure.
2. Configure proxy settings (HTTPS_PROXY / JVM https.proxyHost) if you are behind a corporate proxy.
3. Retry later if the repository is down; check the registry's status page.
4. Fix DNS/VPN/TLS trust issues (import corporate CA into the truststore) as appropriate.

// shell: probe reachability before resolving packages
// curl -fsS --max-time 10 -o /dev/null "$URL" && echo ok || echo 'package host unreachable'

// catch ioErrorMakingHttpGet and retry with backoff
try {
  resolvePackages();
} catch (PackageLoadError e) {
  if (e.getCode().equals("ioErrorMakingHttpGet")) {
    retryWithBackoff(3);
  } else { throw e; }
}

When it happens

Trigger: httpClient.send in openExternalUri throws IOException — unreachable host, refused connection, DNS resolution failure, TLS handshake failure, socket/read timeout, or the connection being reset mid-download.

Common situations: No internet or DNS misconfiguration; corporate proxy/firewall blocking the package repository host; repository temporarily down; VPN required; TLS interception with an untrusted certificate.

Understand the failure class

Background: 'Something went wrong' / 'Request failed (500)' / 'HTTP error! status: 404' — what failed HTTP requests actually mean and how to find the real cause — this error's family across 28 libraries.

Related errors

• errorConnectingToHost
• invalidDependencyMetadata
• httpTooManyRedirects
• httpRedirectNoLocation
• invalidPackageZipChecksum

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