{"record":{"id":"efd313661ea5edaf","repo":"apple/pkl","slug":"invalidpackagezipchecksum","errorCode":"invalidPackageZipChecksum","errorMessage":"invalidPackageZipChecksum","messagePattern":"invalidPackageZipChecksum","errorType":"error_code","errorClass":"PackageLoadError","httpStatus":null,"severity":"critical","filePath":"pkl-core/src/main/java/org/pkl/core/packages/PackageResolvers.java","lineNumber":165,"sourceCode":"      }\n    }\n\n    protected DigestInputStream newDigestInputStream(InputStream in) {\n      try {\n        var md = MessageDigest.getInstance(\"SHA-256\");\n        return new DigestInputStream(in, md);\n      } catch (NoSuchAlgorithmException e) {\n        // All JDK's ship with SHA-256\n        throw new VmExceptionBuilder().unreachableCode().build();\n      }\n    }\n\n    protected void verifyPackageZipBytes(\n        PackageUri packageUri, DependencyMetadata dependencyMetadata, byte[] computedChecksum) {\n      var checksum = ByteArrayUtils.toHex(computedChecksum);\n      var expectedChecksum = dependencyMetadata.getPackageZipChecksums().getSha256();\n      if (!checksum.equals(expectedChecksum)) {\n        throw new PackageLoadError(\n            \"invalidPackageZipChecksum\",\n            packageUri.getDisplayName(),\n            checksum,\n            expectedChecksum,\n            dependencyMetadata.getPackageZipUrl());\n      }\n    }\n\n    protected void verifyPackageMetadataBytes(\n        PackageUri packageUri, URI requestUri, Checksums checksums, byte[] computedChecksum) {\n      var expectedChecksum = checksums.getSha256();\n      var checksum = ByteArrayUtils.toHex(computedChecksum);\n      // Qualify of life improvement: we have a lot of projects in our language snippet tests.\n      // To avoid having to update checksum values in their PklProject.deps.json files, every time\n      // a package changes, we set their checksum value to \"$skipChecksumVerification\".\n      // We keep two tests that do test checksum verification.\n      if (IoUtils.isTestMode() && expectedChecksum.equals(\"$skipChecksumVerification\")) {\n        return;","sourceCodeStart":147,"sourceCodeEnd":183,"githubUrl":"https://github.com/apple/pkl/blob/f3efcbfc9b60d30053b0536d664948d7aa1b8673/pkl-core/src/main/java/org/pkl/core/packages/PackageResolvers.java#L147-L183","documentation":"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.","triggerScenarios":"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.","commonSituations":"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.","solutions":["Retry the download — a transient network error may have corrupted the zip.","Clear any local package cache for this package and re-resolve so it fetches fresh bytes.","Pin a different package version whose zip/checksum are consistent.","If you maintain the repository, re-upload the zip and update DependencyMetadata.json so sha256 matches (compute with sha256sum)."],"exampleFix":"// shell check before trusting the repo\n// after: recompute and update metadata\n// sha256sum pkg.zip  # put this value into DependencyMetadata.json packageZipChecksums.sha256","handlingStrategy":"retry","validationCode":"// shell: compare served zip checksum against metadata before resolving\n// expected=$(curl -fsSL \"$META_URL\" | jq -r .packageZipChecksums.sha256)\n// actual=$(curl -fsSL \"$ZIP_URL\" | sha256sum | cut -d' ' -f1)\n// [ \"$expected\" = \"$actual\" ] && echo ok || echo mismatch","typeGuard":null,"tryCatchPattern":"// catch PackageLoadError with code invalidPackageZipChecksum, clear the package cache, retry once\ntry {\n  pkl.project.resolve();\n} catch (PackageLoadError e) {\n  if (e.getCode().equals(\"invalidPackageZipChecksum\")) {\n    clearPackageCache();\n    pkl.project.resolve(); // retry with fresh bytes\n  } else { throw e; }\n}","preventionTips":["Never re-publish a zip at the same URL without updating metadata checksums.","Keep mirrors in sync with upstream before clients resolve.","Avoid lossy proxies/middleboxes for artifact downloads."],"tags":["pkl","package-management","checksum","security"],"backgroundTag":"checksum-mismatch","analyzedSha":"f3efcbfc9b60d30053b0536d664948d7aa1b8673","analyzedAt":"2026-09-08T13:10:45.570Z","contentChangedAt":"2026-09-08T13:10:45.570Z","schemaVersion":2},"datasetVersion":"2026-09-14T11:17:12.474Z"}