apple/pkl · error · PackageLoadError

unresolvedProjectDependency

unresolvedProjectDependency

Error message

unresolvedProjectDependency

What it means

While wiring a project's declared local dependencies to their resolved counterparts, Pkl looks each declared package URI up in the set of resolved project dependencies. If no resolved dependency exists for a declared local dependency's package URI, this PackageLoadError is thrown, indicating PklProject.deps.json is out of date or incomplete.

Source

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

          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);
      if (resolvedDep == null) {
        throw new PackageLoadError("unresolvedProjectDependency", packageUri);
      }
      checkProjectDependencyOutOfDate(declaredDeps.projectFileUri(), packageUri, resolvedDep);
      ret.put(entry.getKey(), resolvedDep);
    }
    for (var entry : declaredDeps.remoteDependencies().entrySet()) {
      var remoteDep = entry.getValue();
      var packageUri = CanonicalPackageUri.fromPackageUri(remoteDep.getPackageUri());
      var resolvedDep = resolvedProjectDeps.get(packageUri);
      if (resolvedDep == null) {
        throw new PackageLoadError("unresolvedProjectDependency", entry.getValue().getPackageUri());
      }
      checkProjectDependencyOutOfDate(
          declaredDeps.projectFileUri(), remoteDep.getPackageUri(), resolvedDep);
      ret.put(entry.getKey(), resolvedDep);
    }
    return ret;
  }

View on GitHub (pinned to f3efcbfc9b)

Solutions

1. Run `pkl project resolve` to regenerate PklProject.deps.json with the missing dependency.
2. Check for typos in the dependency's package URI in PklProject.
3. Ensure the dependency is also declared/resolvable transitively (the exporting project must declare it).
4. Delete PklProject.deps.json and re-run `pkl project resolve` if the file is corrupted.

Example fix

# before: dependency added to PklProject but not resolved
$ pkl project resolve
# regenerates PklProject.deps.json including the new package

#!/bin/sh
# before evaluating, ensure every declared dependency is present in the lockfile
pkl project resolve
# optionally verify nothing changed:
git diff --exit-code PklProject.deps.json

try {
  depsManager.resolvedDeps();
} catch (PackageLoadError e) {
  if (e.getMessage().startsWith("Did not find a resolved dependency")) {
    throw new BuildException("Unresolved dependency; run 'pkl project resolve'", e);
  }
  throw e;
}

When it happens

Trigger: doBuildResolvedDependenciesForProject (via ensureDependenciesInitialized or resolvedDeps) iterating declaredDeps.localDependencies(): resolvedProjectDeps.get(CanonicalPackageUri.fromPackageUri(packageUri)) returns null for a declared local dependency.

Common situations: Adding a new dependency to PklProject without running `pkl project resolve`; corrupted or truncated PklProject.deps.json; package URI typo so the declared URI never matches anything resolved; a transitive project dependency that was never resolved.

Understand the failure class

Background: "not installed", "pip install", "required for": how missing-dependency errors surface across open-source libraries — this error's family across 34 libraries.

Related errors

• projectDependenciesOutOfDateInProject
• projectDependenciesLocalDependencyOutOfSync
• projectDependenciesOutOfDateInPackage
• cannotLoadProjectDepsJson
• invalidProjectDepsJson

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