apple/pkl · error · IllegalArgumentException

Invalid Pkl distribution: Unexpected error loading service o

Error message

Invalid Pkl distribution: Unexpected error loading service of type `%s` from Jar file `%s`.

What it means

When ServiceLoader fails to instantiate the ExecutorSpi service, it throws ServiceConfigurationError (e.g. the implementation class is missing, fails to initialize, or a dependency is absent). PklDistribution wraps this in IllegalArgumentException "Unexpected error loading service" with the original error as cause. This means the jar declares the service but it cannot actually be loaded.

Source

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

      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;
    }

    String evaluatePath(Path modulePath, ExecutorOptions options) {
      var currentThread = Thread.currentThread();
      var prevContextClassLoader = currentThread.getContextClassLoader();
      // Truffle loads stuff from context class loader, so set it to our class loader

View on GitHub (pinned to f3efcbfc9b)

Solutions

Inspect the cause (ServiceConfigurationError) for the real load failure (missing class, initializer exception)
Replace the jar with a pristine official Pkl distribution fat jar
Check JVM version compatibility with the jar's target class-file version
Fix shading/relocation that broke the SPI implementation class

Example fix

// before
new PklDistribution(repackagedJar, cl); // ServiceConfigurationError
// after
catch (IllegalArgumentException e) {
  log.error("pkl distribution failed to load", e.getCause());
  throw e;
}
new PklDistribution(officialPklJar, cl);

Defensive patterns

Strategy: try-catch

Validate before calling

try (var in = new URL("jar:" + jar.toUri() + "!/org/pkl/executor/spi/").openStream()) { /* spi classes reachable */ } catch (IOException e) { throw new IllegalStateException("cannot read SPI classes from " + jar, e); }

Type guard

boolean canLoadSpiClass(ClassLoader cl, Path jar) { try { Class.forName("org.pkl.executor.spi.ExecutorSpi", false, cl); return true; } catch (ClassNotFoundException e) { return false; } }

Try / catch

try { new PklDistribution(jar, cl); } catch (IllegalArgumentException e) { Throwable c = e.getCause(); if (c instanceof ServiceConfigurationError sce) log.error("SPI load failed", sce.getCause()); throw e; }

Prevention

Always inspect the ServiceConfigurationError cause chain
Run a startup smoke test that loads the distribution
Avoid repackaging pkl jars; use the official artifact
Match JVM version to the jar's bytecode target

When it happens

Trigger: Distribution jar declares META-INF/services for ExecutorSpi but the implementation class cannot be loaded or instantiated: broken/incompatible jar, missing transitive classes after shading, or a ServiceConfigurationError from a static initializer failure.

Common situations: Manually rebuilt or repackaged Pkl jars; conflicting dependency versions on the classpath; running on a JVM incompatible with the jar's bytecode version; partially corrupted jar files.

Related errors

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