apple/pkl · error · PackageLoadError

projectDependenciesOutOfDateInProject

projectDependenciesOutOfDateInProject

Error message

projectDependenciesOutOfDateInProject

What it means

When a project declares a dependency on a (remote) package whose version is newer than the version recorded in PklProject.deps.json, Pkl refuses to build resolved dependencies and throws this error. The lockfile resolves an older version, so the declared requirement cannot be satisfied; running `pkl project resolve` upgrades the lockfile.

Source

Thrown at pkl-core/src/main/java/org/pkl/core/module/ProjectDependenciesManager.java:127

    // TODO: check circular imports (should not be possible)
    for (var declaredDeps : localProjectDependencies.localDependencies().values()) {
      ensureLocalProjectDependencyInitialized(declaredDeps, projectDeps);
    }
  }

  private void checkProjectDependencyOutOfDate(
      URI projectFileUri, PackageUri declaredPackage, Dependency resolvedDependency) {
    // local dependencies must match up exactly (they are expected to always stay in sync).
    if (resolvedDependency instanceof LocalDependency localDependency
        && !declaredPackage.getVersion().equals(localDependency.getVersion())) {
      throw new PackageLoadError(
          "projectDependenciesLocalDependencyOutOfSync",
          projectFileUri,
          declaredPackage.getDisplayName(),
          resolvedDependency.getPackageUri().getDisplayName());
    }
    if (resolvedDependency.getVersion().compareTo(declaredPackage.getVersion()) < 0) {
      throw new PackageLoadError(
          "projectDependenciesOutOfDateInProject",
          projectFileUri,
          declaredPackage.getDisplayName(),
          resolvedDependency.getPackageUri().getDisplayName());
    }
  }

  private Map<String, Dependency> doBuildResolvedDependenciesForProject(
      DeclaredDependencies declaredDeps, ProjectDeps resolvedProjectDeps) {
    var ret =
        new HashMap<String, Dependency>(
            declaredDeps.remoteDependencies().size() + declaredDeps.localDependencies().size());
    for (var entry : declaredDeps.localDependencies().entrySet()) {
      var localDeclaredDependencies = entry.getValue();
      var packageUri = localDeclaredDependencies.myPackageUri();
      assert packageUri != null;
      var canonicalPackageUri = CanonicalPackageUri.fromPackageUri(packageUri);
      var resolvedDep = resolvedProjectDeps.get(canonicalPackageUri);

View on GitHub (pinned to f3efcbfc9b)

Solutions

  1. Run `pkl project resolve` to refresh PklProject.deps.json to the newly declared version.
  2. If the newer version was not intended, revert the dependency version in PklProject back to the resolved version.
  3. Ensure PklProject.deps.json is committed alongside PklProject dependency changes.
  4. Verify the resolved dependency source (cache/repository) actually offers the declared version, then re-resolve.

Example fix

// before (PklProject)
"dependencies": { "my.pkg": { "uri": "package://...", "version": "2.0.0" } }
// PklProject.deps.json still resolves 1.9.0
// after
$ pkl project resolve
// deps.json now resolves 2.0.0
Defensive patterns

Strategy: try-catch

Validate before calling

// before evaluating, compare declared vs resolved versions
java.util.Set<String> declared = readDeclaredVersions("PklProject");
java.util.Set<String> resolved = readResolvedVersions("PklProject.deps.json");
if (declared.entrySet().stream().anyMatch(e -> declared.get(e.getKey()).compareTo(resolved.get(e.getKey())) > 0)) {
  throw new IllegalStateException("PklProject.deps.json is stale; run 'pkl project resolve'");
}

Try / catch

try {
  depsManager.resolvedDeps();
} catch (PackageLoadError e) {
  if (e.getMessage().contains("newer than what is declared")) {
    throw new BuildException("Dependency declared newer than lockfile; run 'pkl project resolve'", e);
  }
  throw e;
}

Prevention

When it happens

Trigger: checkProjectDependencyOutOfDate (invoked from doBuildResolvedDependenciesForProject) finds resolvedDependency.getVersion().compareTo(declaredPackage.getVersion()) < 0 — the PklProject declares a version greater than the resolved one in PklProject.deps.json.

Common situations: Hand-editing the dependency version in PklProject to a newer release without re-resolving; pulling code where someone bumped a dependency but did not commit updated PklProject.deps.json; CI environments with a stale lockfile.

Related errors

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