{"record":{"id":"0a1ec33a76d73b1f","repo":"apple/pkl","slug":"projectdependencieslocaldependencyoutofsync","errorCode":"projectDependenciesLocalDependencyOutOfSync","errorMessage":"projectDependenciesLocalDependencyOutOfSync","messagePattern":"projectDependenciesLocalDependencyOutOfSync","errorType":"error_code","errorClass":"PackageLoadError","httpStatus":null,"severity":"error","filePath":"pkl-core/src/main/java/org/pkl/core/module/ProjectDependenciesManager.java","lineNumber":120,"sourceCode":"    // turn `package:` scheme into `projectpackage`: scheme\n    var uri = PackageUri.create(\"project\" + localProjectDependencies.myPackageUri());\n    if (localPackageDependencies.containsKey(uri)) {\n      return;\n    }\n    var resolvedDeps = doBuildResolvedDependenciesForProject(localProjectDependencies, projectDeps);\n    localPackageDependencies.put(uri, resolvedDeps);\n    // TODO: check circular imports (should not be possible)\n    for (var declaredDeps : localProjectDependencies.localDependencies().values()) {\n      ensureLocalProjectDependencyInitialized(declaredDeps, projectDeps);\n    }\n  }\n\n  private void checkProjectDependencyOutOfDate(\n      URI projectFileUri, PackageUri declaredPackage, Dependency resolvedDependency) {\n    // local dependencies must match up exactly (they are expected to always stay in sync).\n    if (resolvedDependency instanceof LocalDependency localDependency\n        && !declaredPackage.getVersion().equals(localDependency.getVersion())) {\n      throw new PackageLoadError(\n          \"projectDependenciesLocalDependencyOutOfSync\",\n          projectFileUri,\n          declaredPackage.getDisplayName(),\n          resolvedDependency.getPackageUri().getDisplayName());\n    }\n    if (resolvedDependency.getVersion().compareTo(declaredPackage.getVersion()) < 0) {\n      throw new PackageLoadError(\n          \"projectDependenciesOutOfDateInProject\",\n          projectFileUri,\n          declaredPackage.getDisplayName(),\n          resolvedDependency.getPackageUri().getDisplayName());\n    }\n  }\n\n  private Map<String, Dependency> doBuildResolvedDependenciesForProject(\n      DeclaredDependencies declaredDeps, ProjectDeps resolvedProjectDeps) {\n    var ret =\n        new HashMap<String, Dependency>(","sourceCodeStart":102,"sourceCodeEnd":138,"githubUrl":"https://github.com/apple/pkl/blob/f3efcbfc9b60d30053b0536d664948d7aa1b8673/pkl-core/src/main/java/org/pkl/core/module/ProjectDependenciesManager.java#L102-L138","documentation":"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`.","triggerScenarios":"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.","commonSituations":"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.","solutions":["Run `pkl project resolve` in the project directory to regenerate PklProject.deps.json.","Make the declared dependency version match the local package's current version (align the version fields).","Commit PklProject.deps.json together with any local-package version bump so they stay in sync.","If the version change was accidental, revert the local package's version back to the resolved value."],"exampleFix":"# before: local package version bumped, deps file stale\n# PklProject: version 2.0.0, PklProject.deps.json: 1.5.0\n# after\n$ pkl project resolve\n# regenerates PklProject.deps.json with version 2.0.0","handlingStrategy":"try-catch","validationCode":"#!/bin/sh\n# before evaluating, verify local deps are in sync\npkl project resolve --dry-run 2>/dev/null || pkl project resolve","typeGuard":null,"tryCatchPattern":"try {\n  depsManager.resolvedDeps();\n} catch (PackageLoadError e) {\n  if (e.getMessage().contains(\"local package whose version doesn't match\")) {\n    throw new BuildException(\"Local dependency out of sync; run 'pkl project resolve'\", e);\n  }\n  throw e;\n}","preventionTips":["Always run `pkl project resolve` after bumping a local package's version.","Commit PklProject.deps.json together with PklProject version changes in the same commit.","Add a pre-commit/CI check that re-resolves and diffs PklProject.deps.json.","Never hand-edit PklProject.deps.json for local dependencies."],"tags":["pkl","dependencies","version-mismatch","local-dependency"],"backgroundTag":"dependency-version-mismatch","analyzedSha":"f3efcbfc9b60d30053b0536d664948d7aa1b8673","analyzedAt":"2026-09-08T13:10:45.570Z","contentChangedAt":"2026-09-08T13:10:45.570Z","schemaVersion":2},"datasetVersion":"2026-09-14T16:17:12.679Z"}