apple/pkl · error · ExecutorException

Cannot find Pkl module

Error message

Cannot find Pkl module `%s`.

What it means

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.

Solutions

1. Verify the path exists and is a file: Files.isRegularFile(path)
2. Resolve relative paths against the intended base directory before calling evaluatePath
3. Print the display path from the error and compare with the actual file location
4. If loading from a package/resource, resolve it to a local file path first

Example fix

// before
executor.evaluatePath(Path.of("gen/myconfig.pkl"), options);
// after
Path p = baseDir.resolve("gen/myconfig.pkl").normalize();
if (!Files.isRegularFile(p)) throw new IllegalArgumentException("module missing: " + p);
executor.evaluatePath(p, options);

Path p = baseDir.resolve(moduleArg).normalize();
if (!Files.isRegularFile(p)) throw new IllegalArgumentException("Pkl module not found: " + p);

boolean isExistingModule(Path p) { return p != null && Files.isRegularFile(p); }

try { executor.evaluatePath(p, options); } catch (ExecutorException e) { throw new UserInputException("Module path invalid: " + p, e); }

When it happens

Trigger: 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.

Common situations: 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.

Understand the failure class

Background: "File not found" and ENOENT errors: why libraries can't find a file that should exist — this error's family across 50 libraries.

Related errors

• cannotFindResource
• cannotLoadProjectDepsJson
• Failed to write to $depsFile
• I/O error loading Pkl module
• Invalid Pkl distribution: Cannot find Jar file

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

Appendix: source

Thrown at pkl-executor/src/main/java/org/pkl/executor/EmbeddedExecutor.java:68

  // for testing only
  EmbeddedExecutor(List<Path> pklFatJars, ClassLoader pklExecutorClassLoader) {
    for (var jarFile : pklFatJars) {
      pklDistributions.add(new PklDistribution(jarFile, pklExecutorClassLoader));
    }
  }

  public String evaluatePath(Path modulePath, ExecutorOptions options) {
    logger.info("Started evaluating Pkl module. modulePath={} options={}", modulePath, options);

    long startTime = System.nanoTime();

    Version requestedVersion = null;
    PklDistribution distribution = null;
    String output;

    try {
      if (!Files.isRegularFile(modulePath)) {
        throw new ExecutorException(
            String.format("Cannot find Pkl module `%s`.", toDisplayPath(modulePath, options)));
      }

      // Note that version detection for the given module happens before security checks for its
      // evaluation.
      // This should be acceptable because version detection only involves the module passed
      // directly to the executor
      // (but not any modules imported by it) and only requires parsing (but not evaluating) the
      // module.
      requestedVersion = detectRequestedPklVersion(modulePath, options);
      distribution = findCompatibleDistribution(modulePath, requestedVersion, options);
      output = distribution.evaluatePath(modulePath, options);
    } catch (RuntimeException e) {
      // Could log exception, but this would violate "don't log and throw",
      // and Pkl stack trace might contain semi-sensitive information.
      logFinished(modulePath, false, requestedVersion, distribution, startTime, System.nanoTime());
      throw e;
    }

View on GitHub (pinned to f3efcbfc9b)