apple/pkl · error · IllegalArgumentException

Invalid Pkl distribution: Cannot find service of type `%s` i

Error message

Invalid Pkl distribution: Cannot find service of type `%s` in Jar file `%s`.

What it means

PklDistribution loads the jar's ExecutorSpi implementation via ServiceLoader. If the iterator is empty (NoSuchElementException) the jar contains no META-INF/services registration for ExecutorSpi, so it is not a valid Pkl distribution jar, and IllegalArgumentException is thrown.

Source

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

    /**
     * @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(
                "Invalid Pkl distribution: Unexpected error loading service of type `%s` from Jar file `%s`.",
                ExecutorSpi.class.getTypeName(), pklFatJar),
            e);
      }

      // convert to normal to allow running with a dev version
      version = Version.parse(executorSpi.getPklVersion()).toNormal();
    }

    Version getVersion() {
      return version;

View on GitHub (pinned to f3efcbfc9b)

Solutions

1. Use the official pkl fat jar as the distribution jar
2. Verify the jar contains META-INF/services/org.pkl.executor.ExecutorSpi (unzip -l)
3. Fix shading/assembly configs (e.g. ServicesResourceTransformer) that strip service files
4. Ensure the jar's Pkl version provides the ExecutorSpi interface

Example fix

// before
new PklDistribution(Path.of("app-libs.jar"), cl); // wrong jar
// after
new PklDistribution(Path.of("pkl-0.27.2-fat.jar"), cl);

try (var zf = new ZipFile(jar.toFile())) {
  if (zf.getEntry("META-INF/services/org.pkl.executor.ExecutorSpi") == null)
    throw new IllegalStateException(jar + " is not a Pkl distribution (no ExecutorSpi service)");
}

boolean isPklDistributionJar(Path jar) throws IOException { try (var zf = new ZipFile(jar.toFile())) { return zf.getEntry("META-INF/services/org.pkl.executor.ExecutorSpi") != null; } }

try { new PklDistribution(jar, cl); } catch (IllegalArgumentException e) { if (e.getMessage().contains("Cannot find service")) { /* wrong jar */ } throw e; }

When it happens

Trigger: Passing a jar that is not a Pkl distribution (missing META-INF/services/<ExecutorSpi> file), a fat jar built without the service descriptor, or a Pkl version whose SPI class differs.

Common situations: Building a slim/shaded jar that dropped META-INF/services entries; accidentally pointing the executor at an application jar instead of the pkl distribution jar; mixing jars from different Pkl releases.

Related errors

• Invalid Pkl distribution: Cannot find Jar file `%s`.
• Invalid Pkl distribution: Unexpected error loading service o
• No security manager set.
• invalidUri
• externalReaderDoesNotSupportScheme

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