{"record":{"id":"38326dff5040dddf","repo":"apple/pkl","slug":"invalid-pkl-distribution-unexpected-error-loading","errorCode":null,"errorMessage":"Invalid Pkl distribution: Unexpected error loading service of type `%s` from Jar file `%s`.","messagePattern":"Invalid Pkl distribution: Unexpected error loading service of type `(.+?)` from Jar file `(.+?)`\\.","errorType":"exception","errorClass":"IllegalArgumentException","httpStatus":null,"severity":"error","filePath":"pkl-executor/src/main/java/org/pkl/executor/EmbeddedExecutor.java","lineNumber":210,"sourceCode":"      if (!Files.isRegularFile(pklFatJar)) {\n        throw new IllegalArgumentException(\n            String.format(\"Invalid Pkl distribution: Cannot find Jar file `%s`.\", pklFatJar));\n      }\n\n      pklDistributionClassLoader =\n          new PklDistributionClassLoader(pklFatJar, pklExecutorClassLoader);\n      var serviceLoader = ServiceLoader.load(ExecutorSpi.class, pklDistributionClassLoader);\n\n      try {\n        executorSpi = serviceLoader.iterator().next();\n      } catch (NoSuchElementException e) {\n        throw new IllegalArgumentException(\n            String.format(\n                \"Invalid Pkl distribution: Cannot find service of type `%s` in Jar file `%s`.\",\n                ExecutorSpi.class.getTypeName(), pklFatJar));\n\n      } catch (ServiceConfigurationError e) {\n        throw new IllegalArgumentException(\n            String.format(\n                \"Invalid Pkl distribution: Unexpected error loading service of type `%s` from Jar file `%s`.\",\n                ExecutorSpi.class.getTypeName(), pklFatJar),\n            e);\n      }\n\n      // convert to normal to allow running with a dev version\n      version = Version.parse(executorSpi.getPklVersion()).toNormal();\n    }\n\n    Version getVersion() {\n      return version;\n    }\n\n    String evaluatePath(Path modulePath, ExecutorOptions options) {\n      var currentThread = Thread.currentThread();\n      var prevContextClassLoader = currentThread.getContextClassLoader();\n      // Truffle loads stuff from context class loader, so set it to our class loader","sourceCodeStart":192,"sourceCodeEnd":228,"githubUrl":"https://github.com/apple/pkl/blob/f3efcbfc9b60d30053b0536d664948d7aa1b8673/pkl-executor/src/main/java/org/pkl/executor/EmbeddedExecutor.java#L192-L228","documentation":"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.","triggerScenarios":"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.","commonSituations":"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.","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"],"exampleFix":"// before\nnew PklDistribution(repackagedJar, cl); // ServiceConfigurationError\n// after\ncatch (IllegalArgumentException e) {\n  log.error(\"pkl distribution failed to load\", e.getCause());\n  throw e;\n}\nnew PklDistribution(officialPklJar, cl);","handlingStrategy":"try-catch","validationCode":"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); }\n","typeGuard":"boolean canLoadSpiClass(ClassLoader cl, Path jar) { try { Class.forName(\"org.pkl.executor.spi.ExecutorSpi\", false, cl); return true; } catch (ClassNotFoundException e) { return false; } }\n","tryCatchPattern":"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; }\n","preventionTips":["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"],"tags":["pkl","jar","serviceloader","classloading"],"backgroundTag":"class-not-found","analyzedSha":"f3efcbfc9b60d30053b0536d664948d7aa1b8673","analyzedAt":"2026-09-08T13:10:45.570Z","contentChangedAt":"2026-09-08T13:10:45.570Z","schemaVersion":2},"datasetVersion":"2026-09-14T11:17:12.474Z"}