apple/pkl · error · PackageLoadError

cannotFindDependencyInProject

cannotFindDependencyInProject

Error message

Cannot find a dependency named `{0}`, because it is not declared in the current project.

What it means

Thrown when a dependency import names a package that is not present in the current project's declared dependencies. The lookup in projectDependenciesManager.getDependencies() returned null for the requested name.

Source

Thrown at pkl-core/src/main/java/org/pkl/core/util/IoUtils.java:438

      throws IOException, ExternalReaderProcessException {
    var parsed = parseDependencyNotation(notation);
    var name = parsed.getFirst();
    var path = parsed.getSecond();
    var projectDependenciesManager = VmContext.get(null).getProjectDependenciesManager();
    if (!moduleKey.hasHierarchicalUris() && projectDependenciesManager != null) {
      throw new PackageLoadError(
          "cannotResolveDependencyWithoutHierarchicalUris",
          projectDependenciesManager.getProjectFileUri());
    }
    if (projectDependenciesManager == null
        || !projectDependenciesManager.hasUri(moduleKey.getUri())) {
      throw new PackageLoadError("cannotResolveDependencyNoProject");
    }
    var dependency = projectDependenciesManager.getDependencies().get(name);
    if (dependency != null) {
      return dependency.getPackageUri().toPackageAssetUri(path).getUri();
    }
    throw new PackageLoadError("cannotFindDependencyInProject", name);
  }

  /**
   * Resolves {@code importUri} against the module key.
   *
   * <p>When {@code importUri} contains a triple-dot, it is resolved if the module key returns true
   * for both {@link ModuleKey#isLocal()} and {@link ModuleKey#hasHierarchicalUris()}. Otherwise, an
   * error is thrown.
   *
   * <p>When {@code importUri} starts with a {@code @}, it is resolved if the module key supports
   * dependency notation ()
   */
  public static URI resolve(SecurityManager securityManager, ModuleKey moduleKey, URI importUri)
      throws URISyntaxException,
          IOException,
          SecurityManagerException,
          ExternalReaderProcessException {
    if (importUri.isAbsolute()) {

View on GitHub (pinned to f3efcbfc9b)

Solutions

1. Add the dependency to the dependencies section of PklProject.yml (pkl project add is the CLI way)
2. Fix the name in the import statement to match the declared dependency
3. Regenerate/update the lockfile after editing PklProject.yml

Example fix

// before (PklProject.yml has no 'mydep')
import "@mydep/config.pkl"
// after
pkl project add mydep@1.0.0
// then import resolves

for dep in collectDependencyImports(files):
  if dep not in pklProject.dependencies: raise KeyError(dep)

try { resolveImport("@dep/...") } catch (PackageLoadError e) { /* print declared dependency names to help fix typo */ }

When it happens

Trigger: resolveProjectDependency fails the final lookup: the code after parsing `@name/...` cannot find `name` among the dependencies declared in PklProject.yml.

Common situations: Typo in the dependency name in the import (`@mydep/` vs declared `my-dep`), dependency used in code but never added to PklProject.yml dependencies, or stale lockfile after renaming a dependency.

Understand the failure class

Background: Record Not Found Errors: "not found", RecordNotFound, and "was not found" — what they mean and how to fix them — this error's family across 28 libraries.

Related errors

• cannotResolveDependencyNoProject
• projectDependenciesLocalDependencyOutOfSync
• projectDependenciesOutOfDateInProject
• unresolvedProjectDependency
• projectDependenciesOutOfDateInPackage

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