{"record":{"id":"87b8110876dc620b","repo":"apple/pkl","slug":"invalidpackagemetadatachecksum","errorCode":"invalidPackageMetadataChecksum","errorMessage":"invalidPackageMetadataChecksum","messagePattern":"invalidPackageMetadataChecksum","errorType":"error_code","errorClass":"PackageLoadError","httpStatus":null,"severity":"critical","filePath":"pkl-core/src/main/java/org/pkl/core/packages/PackageResolvers.java","lineNumber":186,"sourceCode":"            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;\n      }\n      if (!checksum.equals(expectedChecksum)) {\n        throw new PackageLoadError(\n            \"invalidPackageMetadataChecksum\",\n            packageUri.getDisplayName(),\n            checksum,\n            expectedChecksum,\n            requestUri);\n      }\n    }\n\n    protected InputStream openExternalUri(URI uri) throws SecurityManagerException {\n      if (!HttpUtils.isHttpUrl(uri)) {\n        throw new IllegalArgumentException(\"Expected HTTP(S) URL, but got: \" + uri);\n      }\n\n      // treat package assets as resources instead of modules\n      securityManager.checkReadResource(uri);\n      var request = HttpRequest.newBuilder(uri).build();\n      HttpResponse<InputStream> response;\n      try {","sourceCodeStart":168,"sourceCodeEnd":204,"githubUrl":"https://github.com/apple/pkl/blob/f3efcbfc9b60d30053b0536d664948d7aa1b8673/pkl-core/src/main/java/org/pkl/core/packages/PackageResolvers.java#L168-L204","documentation":"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.","triggerScenarios":"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.","commonSituations":"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.","solutions":["Re-run pkl with the project (e.g. pkl project resolve) so dependency checksums are re-fetched and updated to the metadata now served.","Clear cached packages and re-resolve to rule out corruption on your side.","Pin to a different package version whose metadata is stable.","If you operate the repository, restore the original DependencyMetadata.json bytes or republish dependents with the new checksum."],"exampleFix":"// before: stale locked checksum in PklProjectDependencies.json\n// { \"checksum\": \"oldsha...\" }\n// after: regenerate the lockfile\n// pkl project resolve   # rewrites PklProjectDependencies.json with current checksums","handlingStrategy":"validation","validationCode":"// shell: verify metadata checksum against the lockfile value\n// actual=$(curl -fsSL \"$META_URL\" | sha256sum | cut -d' ' -f1)\n// expected=$(jq -r < PklProjectDependencies.json '.checksum')\n// [ \"$actual\" = \"$expected\" ] && echo ok || echo 'stale lockfile; re-run pkl project resolve'","typeGuard":null,"tryCatchPattern":null,"preventionTips":["Re-run `pkl project resolve` after any upstream package republish.","Treat DependencyMetadata.json as immutable; publish new versions instead of editing.","Keep checksum-locked dependencies in version control so drift is visible."],"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"}