{"record":{"id":"6d6b911ab781bb21","repo":"apple/pkl","slug":"cannot-find-pkl-module-s","errorCode":null,"errorMessage":"Cannot find Pkl module `%s`.","messagePattern":"Cannot find Pkl module `(.+?)`\\.","errorType":"exception","errorClass":"ExecutorException","httpStatus":null,"severity":"error","filePath":"pkl-executor/src/main/java/org/pkl/executor/EmbeddedExecutor.java","lineNumber":68,"sourceCode":"  // for testing only\n  EmbeddedExecutor(List<Path> pklFatJars, ClassLoader pklExecutorClassLoader) {\n    for (var jarFile : pklFatJars) {\n      pklDistributions.add(new PklDistribution(jarFile, pklExecutorClassLoader));\n    }\n  }\n\n  public String evaluatePath(Path modulePath, ExecutorOptions options) {\n    logger.info(\"Started evaluating Pkl module. modulePath={} options={}\", modulePath, options);\n\n    long startTime = System.nanoTime();\n\n    Version requestedVersion = null;\n    PklDistribution distribution = null;\n    String output;\n\n    try {\n      if (!Files.isRegularFile(modulePath)) {\n        throw new ExecutorException(\n            String.format(\"Cannot find Pkl module `%s`.\", toDisplayPath(modulePath, options)));\n      }\n\n      // Note that version detection for the given module happens before security checks for its\n      // evaluation.\n      // This should be acceptable because version detection only involves the module passed\n      // directly to the executor\n      // (but not any modules imported by it) and only requires parsing (but not evaluating) the\n      // module.\n      requestedVersion = detectRequestedPklVersion(modulePath, options);\n      distribution = findCompatibleDistribution(modulePath, requestedVersion, options);\n      output = distribution.evaluatePath(modulePath, options);\n    } catch (RuntimeException e) {\n      // Could log exception, but this would violate \"don't log and throw\",\n      // and Pkl stack trace might contain semi-sensitive information.\n      logFinished(modulePath, false, requestedVersion, distribution, startTime, System.nanoTime());\n      throw e;\n    }","sourceCodeStart":50,"sourceCodeEnd":86,"githubUrl":"https://github.com/apple/pkl/blob/f3efcbfc9b60d30053b0536d664948d7aa1b8673/pkl-executor/src/main/java/org/pkl/executor/EmbeddedExecutor.java#L50-L86","documentation":"EmbeddedExecutor.evaluatePath checks that the module path points to a regular file before any evaluation or security checks. If the path does not exist (or is a directory/symlink to nothing), it throws ExecutorException \"Cannot find Pkl module\". It is a pre-flight file existence check for the module passed on the command line / API.","triggerScenarios":"Calling EmbeddedExecutor.evaluatePath(modulePath, options) where Files.isRegularFile(modulePath) is false: typo'd path, module deleted, relative path resolved against an unexpected working directory, or the path is a directory.","commonSituations":"Running the executor from a different working directory than expected; CI checkout missing the module; passing a package name/URI where a local Path is required; a symlink whose target was removed.","solutions":["Verify the path exists and is a file: Files.isRegularFile(path)","Resolve relative paths against the intended base directory before calling evaluatePath","Print the display path from the error and compare with the actual file location","If loading from a package/resource, resolve it to a local file path first"],"exampleFix":"// before\nexecutor.evaluatePath(Path.of(\"gen/myconfig.pkl\"), options);\n// after\nPath p = baseDir.resolve(\"gen/myconfig.pkl\").normalize();\nif (!Files.isRegularFile(p)) throw new IllegalArgumentException(\"module missing: \" + p);\nexecutor.evaluatePath(p, options);","handlingStrategy":"validation","validationCode":"Path p = baseDir.resolve(moduleArg).normalize();\nif (!Files.isRegularFile(p)) throw new IllegalArgumentException(\"Pkl module not found: \" + p);\n","typeGuard":"boolean isExistingModule(Path p) { return p != null && Files.isRegularFile(p); }\n","tryCatchPattern":"try { executor.evaluatePath(p, options); } catch (ExecutorException e) { throw new UserInputException(\"Module path invalid: \" + p, e); }\n","preventionTips":["Resolve relative module paths against a known base directory","Check Files.isRegularFile before evaluation","Avoid symlinks to removable/absent targets","Log the absolute path you pass to the executor"],"tags":["pkl","file-not-found","io"],"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-17T15:17:12.973Z"}