apple/pkl · critical · PklException

invalidDeclaredChecksum

invalidDeclaredChecksum

Error message

ErrorMessages.create("invalidDeclaredChecksum", packageUri.getDisplayName(), computedChecksums.getSha256(), expectedChecksums.getSha256())

What it means

During dependency resolution, the SHA-256 checksum computed from the actually fetched package metadata does not match the checksum declared in the project's dependency checksums file. The resolver fails fast to protect against tampered or changed package contents.

Solutions

Re-resolve dependencies to regenerate PklProjectDependencies with fresh checksums (e.g. pkl project resolve)
Verify the published package was not changed; republish with a new version instead of mutating an existing one
Clear the local package cache in case of a corrupted download
If the checksum is intentionally updated, update the expected checksum to the reported computed value

Defensive patterns

Strategy: retry

Try / catch

try { resolver.resolve(...); } catch (PklException e) { if (e.getMessage().contains("checksum")) { /* regenerate checksums via pkl project resolve or verify package integrity */ } }

Prevention

Never edit PklProjectDependencies checksums by hand
Regenerate checksums after any dependency version bump
Verify published packages are immutable once released
Clear corrupted caches before re-resolving

When it happens

Trigger: resolveDependenciesOfPackageUri (via buildResolvedDependencies) with expectedChecksums present whose sha256 differs from the checksum computed by packageResolver.getDependencyMetadataAndComputeChecksum().

Common situations: A remote package was republished/updated after checksums were generated; editing PklProjectDependencies by hand with a wrong/copy-pasted checksum; a man-in-the-middle or corrupted cache.

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

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

Appendix: source

Thrown at pkl-core/src/main/java/org/pkl/core/project/ProjectDependenciesResolver.java:109

          dependency.getPackageUri().toProjectPackageUri(), dependency.getChecksums());
    }
    for (var localDeclaredDependencies : declaredDependencies.localDependencies().values()) {
      resolveDependencies(localDeclaredDependencies);
    }
  }

  private void resolveDependenciesOfPackageUri(
      PackageUri packageUri, @Nullable Checksums expectedChecksums) {
    try {
      if (alreadyHandledDependencies.contains(packageUri)) {
        return;
      }
      var pair = packageResolver.getDependencyMetadataAndComputeChecksum(packageUri);
      var metadata = pair.first;
      var computedChecksums = pair.second;
      if (expectedChecksums != null) {
        if (!expectedChecksums.getSha256().equals(computedChecksums.getSha256())) {
          throw new PklException(
              ErrorMessages.create(
                  "invalidDeclaredChecksum",
                  packageUri.getDisplayName(),
                  computedChecksums.getSha256(),
                  expectedChecksums.getSha256()));
        }
      }
      var dependencyWithChecksum = new RemoteDependency(packageUri, computedChecksums);
      updateDependency(dependencyWithChecksum);
      EconomicSets.add(alreadyHandledDependencies, packageUri);
      for (var transitiveDependency : metadata.getDependencies().values()) {
        resolveDependenciesOfPackageUri(
            transitiveDependency.getPackageUri().toProjectPackageUri(),
            transitiveDependency.getChecksums());
      }
    } catch (IOException | SecurityManagerException | PackageLoadError e) {
      throw new PklException(e.getMessage(), e);
    }

View on GitHub (pinned to f3efcbfc9b)