apple/pkl · error · PackageLoadError

cannotResolveDependencyNoProject

cannotResolveDependencyNoProject

Error message

Cannot resolve dependency because there is no project found.

What it means

This PackageLoadError is thrown when a dependency import (`@name/...`) is used but no project is found: there is no ProjectDependenciesManager for the session, or the importing module's URI is not the project's URI scope.

Source

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

      return Pair.of(importPath.substring(1), "/");
    }
    return Pair.of(importPath.substring(1, idx), importPath.substring(idx));
  }

  private static URI resolveProjectDependency(ModuleKey moduleKey, String notation)
      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 ()
   */

View on GitHub (pinned to f3efcbfc9b)

Solutions

Run from the project directory or pass --project-dir so PklProject is discovered
Ensure the file doing the import lives inside the project covered by PklProject.yml
Declare the dependency in PklProject.yml before importing it

Example fix

// before
pkl eval ./mod.pkl  # no project loaded
// after
pkl eval --project-dir . ./mod.pkl

Defensive patterns

Strategy: validation

Validate before calling

Path projectDir = findPklProject(cwd);
if (projectDir == null) throw new IllegalStateException("@dep/... imports require a PklProject; run with --project-dir");

Try / catch

try { pkl eval ... } catch (PackageLoadError e) { if (e.getCode().equals("cannotResolveDependencyNoProject")) { /* instruct user to run from project */ } }

Prevention

Always run pkl from a directory containing PklProject.yml (or pass --project-dir)
Declare all @name imports in PklProject.yml dependencies
Verify project detection with `pkl project list`-style tooling before eval

When it happens

Trigger: resolveProjectDependency runs with projectDependenciesManager == null (no PklProject loaded, e.g. running `pkl eval` without --project-dir / no PklProject on the module path) or the manager does not recognize moduleKey.getUri().

Common situations: Evaluating a file that uses `@dep/...` imports without running from a project directory, or forgetting to pass the project so Pkl can find PklProject.yml.

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

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