apple/pkl · error · PackageLoadError

cannotResolveDependencyWithoutHierarchicalUris

cannotResolveDependencyWithoutHierarchicalUris

Error message

Cannot resolve dependency because project URI `{0}` does not have a hierarchical path.

What it means

Project dependency imports (`@name/...`) can only be resolved when the importing module's URI has a hierarchical path. This PackageLoadError fires when the module URI is non-hierarchical yet a project dependencies manager exists, so the dependency notation cannot be anchored to a project file.

Solutions

Import dependencies only from modules within the project directory
Load the module via its file: path in the project instead of a custom/remote scheme
Restructure so dependency resolution happens from a hierarchical module

Example fix

// before
pkl eval https://example.com/mod.pkl  # mod imports @dep/...
// after
pkl eval ./mod.pkl  # local hierarchical module resolves @dep/... via PklProject

Defensive patterns

Strategy: validation

Validate before calling

if (!moduleKey.hasHierarchicalUris()) throw new IllegalStateException("dependency imports need hierarchical module URIs");

Try / catch

try { resolveDependency(notation) } catch (PackageLoadError e) { /* surface project resolution problem to user */ }

Prevention

Use dependency imports only from files inside the project directory
Avoid loading importing modules through custom/opaque readers
Run pkl with the project root as context

When it happens

Trigger: resolveProjectDependency is called with a moduleKey whose URI has no hierarchical path (e.g. an opaque URI) while a ProjectDependenciesManager is registered for the session.

Common situations: Importing a dependency from a module loaded through a reader/scheme that produces opaque URIs (e.g. a custom reader or in-memory module) inside a CLI session with a project.

Understand the failure class

Background: "Invalid URL" errors: why new URL(), URI.parse, and reqwest::Url reject your string — missing scheme, whitespace, and bad path format — this error's family across 39 libraries.

Related errors

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

Appendix: source

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

  public static Pair<String, String> parseDependencyNotation(String importPath) {
    var idx = importPath.indexOf('/');
    if (idx == -1) {
      // treat named dependency without a subpath as the root path.
      // i.e. resolve to `@foo` to `package://example.com/foo@1.0.0#/`
      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

View on GitHub (pinned to f3efcbfc9b)