apple/pkl · error · PackageLoadError

badHttpStatusCode

badHttpStatusCode

Error message

badHttpStatusCode

What it means

PackageLoadError thrown when fetching a package from a remote repository over HTTP returns a status code other than 200. The library requires a successful HTTP response to download package contents; any other status (404, 403, 5xx, etc.) is rejected.

Source

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

      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;

    protected abstract List<PathElement> doListElements(
        PackageAssetUri uri, @Nullable Checksums checksums)
        throws IOException, SecurityManagerException;

    protected abstract boolean doHasElement(PackageAssetUri uri, @Nullable Checksums checksums)

View on GitHub (pinned to f3efcbfc9b)

Solutions

1. Check that the package URI/version is correct and the package exists on the remote repository
2. Run with logging or curl the exact response.uri() reported in the error to see the real status and body
3. If 401/403, configure credentials (e.g. environment variables or Maven settings for the repo)
4. If 5xx or proxy-related, retry later or fix proxy/VPN/firewall settings

Example fix

// before (PklProject dependencies)
"dependencies": { "my-pkg": { "package": "package://example.com/wrong/name@1.0.0" } }
// after
"dependencies": { "my-pkg": { "package": "package://example.com/correct/name@1.0.0" } }

// pre-check the package endpoint before resolving
var conn = URI.create("https://example.com/registry/pkg@1.0.0").toURL().openConnection();
if (((HttpURLConnection) conn).getResponseCode() != 200) {
  throw new IllegalStateException("Package endpoint unavailable: " + ((HttpURLConnection) conn).getResponseCode());
}

try {
  resolvePackage(uri);
} catch (PackageLoadError e) {
  if ("badHttpStatusCode".equals(e.getCode())) {
    // inspect e.getMessage() for status + uri, apply fallback or abort
  }
}

When it happens

Trigger: Calling package resolution APIs that fetch a package zip over HTTPS (e.g. resolving a `package://` dependency) when the remote endpoint answers with a non-200 status; the check is `HttpUtils.checkHasStatusCode200(response)` in `openExternalUri`.

Common situations: Package URL is wrong or the package was removed/published under a different version (404); a private registry requires auth and returns 401/403; a proxy or CDN returns 502/503; corporate firewall intercepts the request.

Understand the failure class

Background: "API error: {status}" and "HTTP 401/403/404/429/5xx" errors: non-2xx HTTP responses explained — this error's family across 27 libraries.

Related errors

• errorConnectingToHost
• httpTooManyRedirects
• httpRedirectNoLocation
• ioErrorMakingHttpGet
• unableToAccessPublishedPackage

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