apple/pkl · error · PackageLoadError

projectDependenciesLocalDependencyOutOfSync

projectDependenciesLocalDependencyOutOfSync

Error message

projectDependenciesLocalDependencyOutOfSync

What it means

Local package dependencies must always be exactly in sync: the version of the declared package must equal the version recorded in PklProject.deps.json. When a project declares a dependency on a local package whose version differs from the resolved local dependency's version, this PackageLoadError is thrown, telling you to re-run `pkl project resolve`.

Source

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

    // turn `package:` scheme into `projectpackage`: scheme
    var uri = PackageUri.create("project" + localProjectDependencies.myPackageUri());
    if (localPackageDependencies.containsKey(uri)) {
      return;
    }
    var resolvedDeps = doBuildResolvedDependenciesForProject(localProjectDependencies, projectDeps);
    localPackageDependencies.put(uri, resolvedDeps);
    // 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>(

View on GitHub (pinned to f3efcbfc9b)

Solutions

  1. Run `pkl project resolve` in the project directory to regenerate PklProject.deps.json.
  2. Make the declared dependency version match the local package's current version (align the version fields).
  3. Commit PklProject.deps.json together with any local-package version bump so they stay in sync.
  4. If the version change was accidental, revert the local package's version back to the resolved value.

Example fix

# before: local package version bumped, deps file stale
# PklProject: version 2.0.0, PklProject.deps.json: 1.5.0
# after
$ pkl project resolve
# regenerates PklProject.deps.json with version 2.0.0
Defensive patterns

Strategy: try-catch

Validate before calling

#!/bin/sh
# before evaluating, verify local deps are in sync
pkl project resolve --dry-run 2>/dev/null || pkl project resolve

Try / catch

try {
  depsManager.resolvedDeps();
} catch (PackageLoadError e) {
  if (e.getMessage().contains("local package whose version doesn't match")) {
    throw new BuildException("Local dependency out of sync; run 'pkl project resolve'", e);
  }
  throw e;
}

Prevention

When it happens

Trigger: checkProjectDependencyOutOfDate is called from doBuildResolvedDependenciesForProject when resolvedDependency is a LocalDependency and declaredPackage.getVersion() does not equal localDependency.getVersion() — i.e. the local package's PklProject version was edited without re-resolving dependencies.

Common situations: Bumping the version of a locally developed package and forgetting to run `pkl project resolve`; a teammate edited the local package version; generated PklProject.deps.json is stale relative to the workspace.

Related errors

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