apple/pkl · error · IllegalArgumentException

Expected HTTP(S) URL, but got:

Error message

Expected HTTP(S) URL, but got: 

What it means

openExternalUri only knows how to fetch package resources over HTTP(S); it throws IllegalArgumentException "Expected HTTP(S) URL, but got: ..." when the URI uses another scheme. This is an internal guard — the package resolver was handed a non-HTTP URI (file:, https-less custom scheme, malformed URI, etc.).

Solutions

1. Check the URL printed in the error and correct it to an http:// or https:// URL in the metadata/project file.
2. Fix the repository base URL in your PklProject or environment so dependent URLs are absolute HTTP(S).
3. If you subclassed PackageResolvers, ensure openExternalUri is only called with HTTP(S) URIs and handle other schemes yourself.
4. Verify the package metadata on the remote repository hasn't been hand-edited to non-HTTP URLs.

Example fix

// before
"packageZipUrl": "file:///opt/pkl/my-pkg.zip"
// after
"packageZipUrl": "https://example.com/pkl/my-pkg-1.0.0.zip"

// check all package URLs in metadata are HTTP(S) before resolving
// jq -r '.. | strings | select(test("^[a-z]+://"))' DependencyMetadata.json | grep -Ev '^https?://' && echo 'found non-HTTP(S) URL' || echo ok

// Java: guard before calling resolvers that require HTTP
static boolean isHttpUri(URI uri) {
  String s = uri.getScheme();
  return s != null && (s.equalsIgnoreCase("http") || s.equalsIgnoreCase("https"));
}

When it happens

Trigger: A package URI, package zip URL, or asset URL in dependency metadata resolves to a non-HTTP(S) scheme (e.g. file://, s3://) or a malformed URI string that still parses as a URI with a non-http(s) scheme; inputStream then routes it to openExternalUri.

Common situations: A locally edited DependencyMetadata.json or PklProjectDependencies.json contains a file:// or custom-scheme URL; a typo in a repository base URL; custom PackageResolvers subclass passing the wrong URI kind.

Understand the failure class

Background: "Invalid URL" errors: why new URL(), URI.parse, and reqwest::Url reject your string — missing scheme, whitespace, and bad path format — this error's family across 39 libraries.

Related errors

• Failed to convert `pkl.base#String` to `java.net.URL`.
• invalidDependencyMetadata
• invalidPackageMetadataChecksum
• invalidPackageZipChecksum
• ioErrorMakingHttpGet

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

Appendix: source

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

      // To avoid having to update checksum values in their PklProject.deps.json files, every time
      // a package changes, we set their checksum value to "$skipChecksumVerification".
      // We keep two tests that do test checksum verification.
      if (IoUtils.isTestMode() && expectedChecksum.equals("$skipChecksumVerification")) {
        return;
      }
      if (!checksum.equals(expectedChecksum)) {
        throw new PackageLoadError(
            "invalidPackageMetadataChecksum",
            packageUri.getDisplayName(),
            checksum,
            expectedChecksum,
            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());
      }

View on GitHub (pinned to f3efcbfc9b)