apple/pkl · critical · PackageLoadError

invalidPackageZipChecksum

invalidPackageZipChecksum

Error message

invalidPackageZipChecksum

What it means

The SHA-256 checksum of the downloaded package zip does not match the packageZipChecksums.sha256 recorded in the dependency metadata. verifyPackageZipBytes compares the computed digest of the fetched zip bytes against the expected checksum and throws invalidPackageZipChecksum on mismatch, protecting against corrupted or tampered artifacts.

Source

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

      }
    }

    protected DigestInputStream newDigestInputStream(InputStream in) {
      try {
        var md = MessageDigest.getInstance("SHA-256");
        return new DigestInputStream(in, md);
      } catch (NoSuchAlgorithmException e) {
        // All JDK's ship with SHA-256
        throw new VmExceptionBuilder().unreachableCode().build();
      }
    }

    protected void verifyPackageZipBytes(
        PackageUri packageUri, DependencyMetadata dependencyMetadata, byte[] computedChecksum) {
      var checksum = ByteArrayUtils.toHex(computedChecksum);
      var expectedChecksum = dependencyMetadata.getPackageZipChecksums().getSha256();
      if (!checksum.equals(expectedChecksum)) {
        throw new PackageLoadError(
            "invalidPackageZipChecksum",
            packageUri.getDisplayName(),
            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;

View on GitHub (pinned to f3efcbfc9b)

Solutions

1. Retry the download — a transient network error may have corrupted the zip.
2. Clear any local package cache for this package and re-resolve so it fetches fresh bytes.
3. Pin a different package version whose zip/checksum are consistent.
4. If you maintain the repository, re-upload the zip and update DependencyMetadata.json so sha256 matches (compute with sha256sum).

Example fix

// shell check before trusting the repo
// after: recompute and update metadata
// sha256sum pkg.zip  # put this value into DependencyMetadata.json packageZipChecksums.sha256

// shell: compare served zip checksum against metadata before resolving
// expected=$(curl -fsSL "$META_URL" | jq -r .packageZipChecksums.sha256)
// actual=$(curl -fsSL "$ZIP_URL" | sha256sum | cut -d' ' -f1)
// [ "$expected" = "$actual" ] && echo ok || echo mismatch

// catch PackageLoadError with code invalidPackageZipChecksum, clear the package cache, retry once
try {
  pkl.project.resolve();
} catch (PackageLoadError e) {
  if (e.getCode().equals("invalidPackageZipChecksum")) {
    clearPackageCache();
    pkl.project.resolve(); // retry with fresh bytes
  } else { throw e; }
}

When it happens

Trigger: Downloading a package zip whose content hash differs from the checksum published in DependencyMetadata.json — e.g. the artifact was re-uploaded without updating metadata, the download was corrupted/truncated, or a mirror served a stale/different zip.

Common situations: A package author re-published a zip at the same URL without bumping the version/checksum; an internal mirror is out of sync with upstream; network middleware corrupts the transfer; a compromised repository serves modified artifacts.

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

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

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