{"record":{"id":"b4abf5251fc1d232","repo":"apple/pkl","slug":"cannotfindmodule","errorCode":"cannotFindModule","errorMessage":"cannotFindModule","messagePattern":"cannotFindModule","errorType":"error_code","errorClass":"VmException","httpStatus":null,"severity":"error","filePath":"pkl-core/src/main/java/org/pkl/core/runtime/ModuleCache.java","lineNumber":217,"sourceCode":"  private ResolvedModuleKey resolve(\n      ModuleKey module, SecurityManager securityManager, @Nullable Node importNode) {\n    try {\n      return module.resolve(securityManager);\n    } catch (SecurityManagerException | PackageLoadError | HttpClientException e) {\n      throw new VmExceptionBuilder().withOptionalLocation(importNode).withCause(e).build();\n    } catch (FileNotFoundException | NoSuchFileException e) {\n      var exceptionBuilder =\n          new VmExceptionBuilder()\n              .withOptionalLocation(importNode)\n              .evalError(\"cannotFindModule\", module.getUri());\n      var path = module.getUri().getPath();\n      if (path != null && path.contains(\"\\\\\")) {\n        exceptionBuilder.withHint(\n            \"To resolve modules in nested directories, use `/` as the directory separator.\");\n      }\n      throw exceptionBuilder.build();\n    } catch (IOException e) {\n      throw new VmExceptionBuilder()\n          .withOptionalLocation(importNode)\n          .evalError(\"ioErrorLoadingModule\", module.getUri())\n          .withCause(e)\n          .build();\n    }\n  }\n}\n","sourceCodeStart":199,"sourceCodeEnd":225,"githubUrl":"https://github.com/apple/pkl/blob/f3efcbfc9b60d30053b0536d664948d7aa1b8673/pkl-core/src/main/java/org/pkl/core/runtime/ModuleCache.java#L199-L225","documentation":"ModuleCache.resolve throws cannotFindModule when a module URI (typically a relative/path or unregistered scheme import) cannot be resolved or loaded by any registered module key factory; the module file does not exist at the resolved location or no factory can handle the URI. If the path contains backslashes, a hint about using `/` as directory separator is attached. IOExceptions during loading surface separately as ioErrorLoadingModule.","triggerScenarios":"`import \"relative/path/to.pkl\"` where the file does not exist; importing a module via a scheme with no registered ModuleKeyFactory; Windows-style backslash paths pasted into imports.","commonSituations":"Wrong working directory when evaluating; missing files in a project layout; typos in module paths; moving modules without updating imports; running on Windows with `\\` separators in import strings.","solutions":["Fix the import path (check spelling and that the file exists relative to the importing module).","Replace backslashes with forward slashes if the path contains `\\`.","Register the appropriate ModuleKeyFactory/module path mapping if using a custom scheme or embedded resolver."],"exampleFix":"// before\nimport \"configs\\settings.pkl\"\n// after\nimport \"configs/settings.pkl\"","handlingStrategy":"validation","validationCode":"fun assertImportable(importerPath: Path, importPath: String) {\n  require('\\\\' !in importPath) { \"use '/' as directory separator\" }\n  val resolved = importerPath.toAbsolutePath().parent!!.resolve(importPath).normalize()\n  require(java.nio.file.Files.exists(resolved)) { \"module not found: $resolved\" }\n}","typeGuard":null,"tryCatchPattern":null,"preventionTips":["Always use forward slashes in module imports","Run evaluations from a stable working directory or use project-relative imports","Verify referenced files exist in version control/CI"],"tags":["pkl","import","module-not-found","path"],"backgroundTag":"file-not-found","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"}