{"record":{"id":"5aeedb2355481c4e","repo":"apple/pkl","slug":"cannotevaluaterelativemoduleuri","errorCode":"cannotEvaluateRelativeModuleUri","errorMessage":"cannotEvaluateRelativeModuleUri","messagePattern":"cannotEvaluateRelativeModuleUri","errorType":"error_code","errorClass":"VmException","httpStatus":null,"severity":"error","filePath":"pkl-core/src/main/java/org/pkl/core/runtime/ModuleResolver.java","lineNumber":44,"sourceCode":"import org.pkl.core.externalreader.ExternalReaderProcessException;\nimport org.pkl.core.module.ModuleKey;\nimport org.pkl.core.module.ModuleKeyFactory;\nimport org.pkl.core.module.ModuleKeys;\n\npublic final class ModuleResolver {\n  private final Collection<ModuleKeyFactory> factories;\n\n  public ModuleResolver(Collection<ModuleKeyFactory> factories) {\n    this.factories = factories;\n  }\n\n  public Collection<ModuleKeyFactory> getFactories() {\n    return factories;\n  }\n\n  public ModuleKey resolve(ModuleSource moduleSource) {\n    if (!moduleSource.getUri().isAbsolute()) {\n      throw new VmExceptionBuilder()\n          .evalError(\"cannotEvaluateRelativeModuleUri\", moduleSource.getUri())\n          .build();\n    }\n    if (moduleSource.getContents() != null) {\n      // `ModuleSource.text()` creates a synthetic module with URI `repl:text`, so it should be\n      // matched to `ModuleKeys.synthetic`.\n      if (moduleSource.getUri().equals(VmUtils.REPL_TEXT_URI)) {\n        return ModuleKeys.synthetic(moduleSource.getUri(), moduleSource.getContents());\n      }\n      return resolveCached(moduleSource.getUri(), moduleSource.getContents());\n    }\n    return resolve(moduleSource.getUri());\n  }\n\n  public ModuleKey resolve(URI moduleUri) {\n    return resolve(moduleUri, null);\n  }\n","sourceCodeStart":26,"sourceCodeEnd":62,"githubUrl":"https://github.com/apple/pkl/blob/f3efcbfc9b60d30053b0536d664948d7aa1b8673/pkl-core/src/main/java/org/pkl/core/runtime/ModuleResolver.java#L26-L62","documentation":"ModuleResolver.resolve throws cannotEvaluateRelativeModuleUri when given a ModuleSource whose URI is not absolute. Module resolution requires an absolute URI to match against registered ModuleKeyFactories; a relative URI has no scheme and cannot be dispatched. This is an internal-argument error: callers must pass ModuleSource with an absolute URI (or use text() to create a synthetic module).","triggerScenarios":"Calling ModuleResolver.resolve(ModuleSource) with a source built from a relative URI, e.g. ModuleSource.get(\"relative.pkl\") instead of an absolute URI; also reached via resolveOutputPaths and various key-resolution helpers.","commonSituations":"Embedding Pkl and passing relative paths straight into resolve instead of resolving them against a base URI or the file system; constructing module sources manually in tests/tools.","solutions":["Convert the relative path to an absolute URI before creating the ModuleSource (e.g. Path.toUri() or resolving against the importing module's URI).","Use ModuleSource.text() if the content is synthetic, or file-based APIs that accept relative paths and resolve them for you.","When using the CLI/Project APIs, let the built-in resolvers handle relative imports instead of calling ModuleResolver directly."],"exampleFix":"// before\nresolver.resolve(ModuleSource.get(\"config/template.pkl\"));\n// after\nvar abs = Paths.get(\"config/template.pkl\").toAbsolutePath().toUri();\nresolver.resolve(ModuleSource.get(abs.toString()));","handlingStrategy":"validation","validationCode":"fun requireAbsoluteUri(src: ModuleSource) {\n  require(src.uri.isAbsolute) { \"ModuleSource URI must be absolute, got: ${src.uri}\" }\n}","typeGuard":null,"tryCatchPattern":null,"preventionTips":["Normalize paths to absolute URIs before constructing ModuleSource","Prefer ModuleSource.text() for synthetic content","Add assertions around custom resolver entry points"],"tags":["pkl","module-resolution","relative-uri","api-misuse"],"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-14T11:17:12.474Z"}