apple/pkl · critical · PackageLoadError

invalidPackageMetadataChecksum

invalidPackageMetadataChecksum

Error message

invalidPackageMetadataChecksum

What it means

The SHA-256 checksum of the fetched dependency metadata (DependencyMetadata.json) does not match the checksum recorded in PklProjectDependencies.json (or the resolved dependency lock). verifyPackageMetadataBytes throws invalidPackageMetadataChecksum when the computed digest differs from the expected one, ensuring the metadata was not altered in transit or at rest. In test mode, the sentinel value "$skipChecksumVerification" bypasses the check.

Source

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

            checksum,
            expectedChecksum,
            dependencyMetadata.getPackageZipUrl());
      }
    }

    protected void verifyPackageMetadataBytes(
        PackageUri packageUri, URI requestUri, Checksums checksums, byte[] computedChecksum) {
      var expectedChecksum = checksums.getSha256();
      var checksum = ByteArrayUtils.toHex(computedChecksum);
      // Qualify of life improvement: we have a lot of projects in our language snippet tests.
      // 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 {

View on GitHub (pinned to f3efcbfc9b)

Solutions

1. Re-run pkl with the project (e.g. pkl project resolve) so dependency checksums are re-fetched and updated to the metadata now served.
2. Clear cached packages and re-resolve to rule out corruption on your side.
3. Pin to a different package version whose metadata is stable.
4. If you operate the repository, restore the original DependencyMetadata.json bytes or republish dependents with the new checksum.

Example fix

// before: stale locked checksum in PklProjectDependencies.json
// { "checksum": "oldsha..." }
// after: regenerate the lockfile
// pkl project resolve   # rewrites PklProjectDependencies.json with current checksums

// shell: verify metadata checksum against the lockfile value
// actual=$(curl -fsSL "$META_URL" | sha256sum | cut -d' ' -f1)
// expected=$(jq -r < PklProjectDependencies.json '.checksum')
// [ "$actual" = "$expected" ] && echo ok || echo 'stale lockfile; re-run pkl project resolve'

When it happens

Trigger: Resolving a dependency whose locked metadata checksum no longer matches what the repository serves — e.g. the metadata file was regenerated/edited on the server, a mirror serves different bytes, or PklProjectDependencies.json holds a stale checksum after the package was re-published.

Common situations: Package re-published in place without updating dependents' checksums; internal registry mirrors out of sync; manual edits to DependencyMetadata.json; switching between proxies that rewrite responses.

Understand the failure class

Background: Checksum mismatch errors: "checksum verification failed", "digest mismatch", "expected vs actual checksum" — what they mean and how to fix them — this error's family across 41 libraries.

Related errors

• invalidPackageZipChecksum
• insufficientModuleTrustLevel
• resourcePastRootDir|modulePastRootDir
• resourceNotInAllowList|moduleNotInAllowList
• No security manager set.

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