apple/pkl · error · IOException

badHttpStatusCode

badHttpStatusCode

Error message

Received unexpected status code `{0}` when making request `GET {1}`.

What it means

HttpUtils.checkHasStatusCode200 verifies an HTTP response returned 200 and otherwise throws an IOException carrying the badHttpStatusCode message with the actual status code and request URI. It indicates the remote server responded, but not with the expected 200 OK.

Solutions

1. Check the printed status code and URI: fix the URL if 404, or supply credentials if 401/403
2. Open the URI in a browser/curl to see the server's error body for details
3. Retry later if 429/5xx, and check proxy/firewall interference
4. Point the import/dependency at a version or path that exists

Example fix

// before
// importing https://example.com/missing.pkl -> 404
import "https://example.com/missing.pkl"
// after
import "https://example.com/present.pkl"

const res = await fetch(url, { method: 'HEAD' });
if (res.status !== 200) throw new Error(`Precheck failed: ${res.status} for ${url}`);

try {
  return fetchModule(uri);
} catch (IOException e) {
  if (e.getMessage().startsWith("Received unexpected status code")) {
    // parse status from message; handle 404 (missing), 401/403 (auth), 5xx (retry)
  } else throw e;
}

When it happens

Trigger: Any HTTP fetch routed through HttpUtils (module/resource downloads over http(s), dependency resolution) where the server returns a non-200 status such as 404, 403, 500, or a redirect that is not followed.

Common situations: Wrong or moved URL (404), missing/invalid credentials (401/403), server-side errors (5xx), rate limiting (429), or a proxy intercepting the request.

Related errors

• badHttpStatusCode
• errorConnectingToHost
• httpRedirectNoLocation
• httpTooManyRedirects
• ioErrorMakingHttpGet

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

Appendix: source

Thrown at pkl-core/src/main/java/org/pkl/core/util/HttpUtils.java:60

  }

  public static boolean isHttpUrl(URI uri) {
    var scheme = uri.getScheme();
    return "https".equalsIgnoreCase(scheme) || "http".equalsIgnoreCase(scheme);
  }

  public static void checkHasStatusCode200(HttpResponse<?> response) throws IOException {
    if (response.statusCode() == 200) return;

    var body = response.body();
    if (body instanceof AutoCloseable closeable) {
      try {
        closeable.close();
      } catch (Exception ignored) {
      }
    }

    throw new IOException(
        ErrorMessages.create("badHttpStatusCode", response.statusCode(), response.uri()));
  }

  public static URI setPort(URI uri, int port) {
    if (port < 0 || port > 65535) {
      throw new IllegalArgumentException(String.valueOf(port));
    }
    try {
      return new URI(
          uri.getScheme(),
          uri.getUserInfo(),
          uri.getHost(),
          port,
          uri.getPath(),
          uri.getQuery(),
          uri.getFragment());
    } catch (URISyntaxException e) {
      throw PklBugException.unreachableCode(); // only port changed

View on GitHub (pinned to f3efcbfc9b)