apple/pkl · error · PackageLoadError

invalidPackageZipUrl

invalidPackageZipUrl

Error message

invalidPackageZipUrl

What it means

Raised in `PackageResolvers.doGetDependencyMetadata` after parsing a package's dependency metadata: the parsed `PackageZipUrl` does not use the HTTPS scheme, so the resolver rejects it with `invalidPackageZipUrl` to prevent downloading package zips over insecure transport. This is a security guard on package-manager metadata.

Solutions

1. Fix the package server/metadata so `packageZipUrl` uses `https://`.
2. If it's your own registry, configure it to advertise HTTPS endpoints (TLS termination in front of the storage).
3. Re-publish or update the affected package version's metadata, then clear any cached metadata and retry.
4. Use the official/standard Pkl package repository whose metadata always declares HTTPS URLs.

Example fix

// before (metadata JSON)
{ "packageZipUrl": "http://registry.example.com/pkgs/my-pkg@1.0.0.zip" }
// after
{ "packageZipUrl": "https://registry.example.com/pkgs/my-pkg@1.0.0.zip" }

function assertHttpsUrl(u) {
  const url = new URL(u);
  if (url.protocol !== "https:") throw new Error(`package zip URL must be https, got ${url.protocol}`);
}

function isHttpsUrl(u) { try { return new URL(u).protocol === "https:"; } catch { return false; } }

try {
  const meta = loadDependencyMetadata(pkgUri);
} catch (e) {
  if (e.code === "invalidPackageZipUrl") { /* fix registry metadata or pin another version */ }
}

When it happens

Trigger: A dependency's metadata file (fetched from a package server) declares a `packageZipUrl` whose scheme is `http` (or any non-https scheme) — e.g. a self-hosted/custom package server publishing metadata with plain-HTTP zip URLs.

Common situations: Running a local or intranet package server that emits `http://` URLs; hand-authored or migrated dependency metadata; proxy setups that rewrite https URLs to http.

Understand the failure class

Background: "Invalid URL" / "URL cannot be empty": fix the malformed or missing URL behind request-construction failures — this error's family across 50 libraries.

Related errors

• insufficientModuleTrustLevel
• invalidPackageMetadataChecksum
• invalidPackageZipChecksum
• Is a directory
• No security manager set.

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

Appendix: source

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

    @Override
    protected DependencyMetadata doGetDependencyMetadata(
        PackageUri packageUri, @Nullable Checksums checksums)
        throws IOException, SecurityManagerException {
      var requestUri = packageUri.getMetadataRequestUri();
      var inputStream = openExternalUri(requestUri);
      if (checksums != null) {
        inputStream = newDigestInputStream(inputStream);
      }
      try (var in = inputStream) {
        var metadataStr = IoUtils.readString(in);
        if (checksums != null) {
          var digestInputStream = (DigestInputStream) in;
          var checksumBytes = digestInputStream.getMessageDigest().digest();
          verifyPackageMetadataBytes(packageUri, requestUri, checksums, checksumBytes);
        }
        var metadata = DependencyMetadata.parse(metadataStr);
        if (!metadata.getPackageZipUrl().getScheme().equalsIgnoreCase("https")) {
          throw invalidPackageZipUrl(packageUri, metadata);
        }
        return metadata;
      } catch (JsonParseException e) {
        throw new PackageLoadError(
            e,
            "invalidDependencyMetadata",
            packageUri.getDisplayName(),
            requestUri,
            e.getMessage());
      }
    }

    @Override
    public void close() throws IOException {
      super.close();
      synchronized (lock) {
        cachedEntries.clear();
        cachedTreePathElementRoots.clear();

View on GitHub (pinned to f3efcbfc9b)