{"record":{"id":"fd144ee153b1ffa8","repo":"apple/pkl","slug":"cannotresolvedependencywithouthierarchicaluris","errorCode":"cannotResolveDependencyWithoutHierarchicalUris","errorMessage":"Cannot resolve dependency because project URI `{0}` does not have a hierarchical path.","messagePattern":"Cannot resolve dependency because project URI `(.+?)` does not have a hierarchical path\\.","errorType":"error_code","errorClass":"PackageLoadError","httpStatus":null,"severity":"error","filePath":"pkl-core/src/main/java/org/pkl/core/util/IoUtils.java","lineNumber":426,"sourceCode":"\n  public static Pair<String, String> parseDependencyNotation(String importPath) {\n    var idx = importPath.indexOf('/');\n    if (idx == -1) {\n      // treat named dependency without a subpath as the root path.\n      // i.e. resolve to `@foo` to `package://example.com/foo@1.0.0#/`\n      return Pair.of(importPath.substring(1), \"/\");\n    }\n    return Pair.of(importPath.substring(1, idx), importPath.substring(idx));\n  }\n\n  private static URI resolveProjectDependency(ModuleKey moduleKey, String notation)\n      throws IOException, ExternalReaderProcessException {\n    var parsed = parseDependencyNotation(notation);\n    var name = parsed.getFirst();\n    var path = parsed.getSecond();\n    var projectDependenciesManager = VmContext.get(null).getProjectDependenciesManager();\n    if (!moduleKey.hasHierarchicalUris() && projectDependenciesManager != null) {\n      throw new PackageLoadError(\n          \"cannotResolveDependencyWithoutHierarchicalUris\",\n          projectDependenciesManager.getProjectFileUri());\n    }\n    if (projectDependenciesManager == null\n        || !projectDependenciesManager.hasUri(moduleKey.getUri())) {\n      throw new PackageLoadError(\"cannotResolveDependencyNoProject\");\n    }\n    var dependency = projectDependenciesManager.getDependencies().get(name);\n    if (dependency != null) {\n      return dependency.getPackageUri().toPackageAssetUri(path).getUri();\n    }\n    throw new PackageLoadError(\"cannotFindDependencyInProject\", name);\n  }\n\n  /**\n   * Resolves {@code importUri} against the module key.\n   *\n   * <p>When {@code importUri} contains a triple-dot, it is resolved if the module key returns true","sourceCodeStart":408,"sourceCodeEnd":444,"githubUrl":"https://github.com/apple/pkl/blob/f3efcbfc9b60d30053b0536d664948d7aa1b8673/pkl-core/src/main/java/org/pkl/core/util/IoUtils.java#L408-L444","documentation":"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.","triggerScenarios":"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.","commonSituations":"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.","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"],"exampleFix":"// before\npkl eval https://example.com/mod.pkl  # mod imports @dep/...\n// after\npkl eval ./mod.pkl  # local hierarchical module resolves @dep/... via PklProject","handlingStrategy":"validation","validationCode":"if (!moduleKey.hasHierarchicalUris()) throw new IllegalStateException(\"dependency imports need hierarchical module URIs\");","typeGuard":null,"tryCatchPattern":"try { resolveDependency(notation) } catch (PackageLoadError e) { /* surface project resolution problem to user */ }","preventionTips":["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"],"tags":["pkl","dependencies","uri-resolution"],"backgroundTag":"invalid-url-format","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"}