apple/pkl · error · IllegalArgumentException

Invalid Pkl distribution: Cannot find Jar file `%s`.

Error message

Invalid Pkl distribution: Cannot find Jar file `%s`.

What it means

The PklDistribution constructor validates the supplied fat jar before loading it. If pklFatJar is not a regular file it throws IllegalArgumentException "Invalid Pkl distribution: Cannot find Jar file". This validates the jar you registered as a Pkl runtime distribution for the embedded executor.

Source

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

  @Override
  public void close() throws Exception {
    for (var pklDistribution : pklDistributions) {
      pklDistribution.close();
    }
  }

  private static final class PklDistribution implements AutoCloseable {
    final URLClassLoader pklDistributionClassLoader;
    final ExecutorSpi executorSpi;
    final Version version;

    /**
     * @throws IllegalArgumentException if the Jar file does not exist or is not a valid Pkl
     *     distribution
     */
    PklDistribution(Path pklFatJar, ClassLoader pklExecutorClassLoader) {
      if (!Files.isRegularFile(pklFatJar)) {
        throw new IllegalArgumentException(
            String.format("Invalid Pkl distribution: Cannot find Jar file `%s`.", pklFatJar));
      }

      pklDistributionClassLoader =
          new PklDistributionClassLoader(pklFatJar, pklExecutorClassLoader);
      var serviceLoader = ServiceLoader.load(ExecutorSpi.class, pklDistributionClassLoader);

      try {
        executorSpi = serviceLoader.iterator().next();
      } catch (NoSuchElementException e) {
        throw new IllegalArgumentException(
            String.format(
                "Invalid Pkl distribution: Cannot find service of type `%s` in Jar file `%s`.",
                ExecutorSpi.class.getTypeName(), pklFatJar));

      } catch (ServiceConfigurationError e) {
        throw new IllegalArgumentException(
            String.format(

View on GitHub (pinned to f3efcbfc9b)

Solutions

1. Verify Files.isRegularFile(pklFatJar) before constructing
2. Fix the path to the Pkl fat jar (absolute path is safest)
3. Ensure the jar is present in the deployment artifact/image
4. Check CI packaging steps that produce/copy the jar

Example fix

// before
var dist = new PklDistribution(Path.of("pkl-cli.jar"), cl);
// after
Path jar = Path.of("/opt/pkl/pkl-0.27.2.jar");
if (!Files.isRegularFile(jar)) throw new IllegalStateException("missing pkl jar: " + jar);
var dist = new PklDistribution(jar, cl);

Path jar = Path.of(distPath);
if (!Files.isRegularFile(jar)) throw new IllegalStateException("pkl fat jar missing: " + jar);

boolean isValidJarPath(Path p) { return p != null && Files.isRegularFile(p) && p.toString().endsWith(".jar"); }

try { new PklDistribution(jar, cl); } catch (IllegalArgumentException e) { throw new ConfigurationException("invalid pkl distribution jar", e); }

When it happens

Trigger: Constructing EmbeddedExecutor.PklDistribution with a Path that does not exist, is a directory, or is a broken symlink; typo'd jar path; jar not copied into the deployment image.

Common situations: Docker images forgetting to COPY the pkl fat jar; relative jar paths resolved against the wrong working directory; renaming artifacts in CI so the expected jar filename no longer exists.

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

• Invalid Pkl distribution: Cannot find service of type `%s` i
• No security manager set.
• invalidUri
• cannotFindCertFile
• externalReaderDoesNotSupportScheme

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