{"record":{"id":"7d13f887bcb5df95","repo":"apple/pkl","slug":"projectdependenciesoutofdateinproject","errorCode":"projectDependenciesOutOfDateInProject","errorMessage":"projectDependenciesOutOfDateInProject","messagePattern":"projectDependenciesOutOfDateInProject","errorType":"error_code","errorClass":"PackageLoadError","httpStatus":null,"severity":"error","filePath":"pkl-core/src/main/java/org/pkl/core/module/ProjectDependenciesManager.java","lineNumber":127,"sourceCode":"    // 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>(\n            declaredDeps.remoteDependencies().size() + declaredDeps.localDependencies().size());\n    for (var entry : declaredDeps.localDependencies().entrySet()) {\n      var localDeclaredDependencies = entry.getValue();\n      var packageUri = localDeclaredDependencies.myPackageUri();\n      assert packageUri != null;\n      var canonicalPackageUri = CanonicalPackageUri.fromPackageUri(packageUri);\n      var resolvedDep = resolvedProjectDeps.get(canonicalPackageUri);","sourceCodeStart":109,"sourceCodeEnd":145,"githubUrl":"https://github.com/apple/pkl/blob/f3efcbfc9b60d30053b0536d664948d7aa1b8673/pkl-core/src/main/java/org/pkl/core/module/ProjectDependenciesManager.java#L109-L145","documentation":"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.","triggerScenarios":"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.","commonSituations":"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.","solutions":["Run `pkl project resolve` to refresh PklProject.deps.json to the newly declared version.","If the newer version was not intended, revert the dependency version in PklProject back to the resolved version.","Ensure PklProject.deps.json is committed alongside PklProject dependency changes.","Verify the resolved dependency source (cache/repository) actually offers the declared version, then re-resolve."],"exampleFix":"// before (PklProject)\n\"dependencies\": { \"my.pkg\": { \"uri\": \"package://...\", \"version\": \"2.0.0\" } }\n// PklProject.deps.json still resolves 1.9.0\n// after\n$ pkl project resolve\n// deps.json now resolves 2.0.0","handlingStrategy":"try-catch","validationCode":"// before evaluating, compare declared vs resolved versions\njava.util.Set<String> declared = readDeclaredVersions(\"PklProject\");\njava.util.Set<String> resolved = readResolvedVersions(\"PklProject.deps.json\");\nif (declared.entrySet().stream().anyMatch(e -> declared.get(e.getKey()).compareTo(resolved.get(e.getKey())) > 0)) {\n  throw new IllegalStateException(\"PklProject.deps.json is stale; run 'pkl project resolve'\");\n}","typeGuard":null,"tryCatchPattern":"try {\n  depsManager.resolvedDeps();\n} catch (PackageLoadError e) {\n  if (e.getMessage().contains(\"newer than what is declared\")) {\n    throw new BuildException(\"Dependency declared newer than lockfile; run 'pkl project resolve'\", e);\n  }\n  throw e;\n}","preventionTips":["Treat PklProject.deps.json as a lockfile: regenerate with `pkl project resolve` after any version bump.","Never hand-edit dependency versions in PklProject without re-resolving.","Ensure CI fails fast with `pkl project resolve && git diff --exit-code PklProject.deps.json`.","Keep PklProject and PklProject.deps.json changes in the same commit."],"tags":["pkl","dependencies","version-mismatch","lockfile"],"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"}