{"record":{"id":"6803854c4624ba0e","repo":"apple/pkl","slug":"invalid-pkl-distribution-cannot-find-service-of-t","errorCode":null,"errorMessage":"Invalid Pkl distribution: Cannot find service of type `%s` in Jar file `%s`.","messagePattern":"Invalid Pkl distribution: Cannot find service of type `(.+?)` in Jar file `(.+?)`\\.","errorType":"exception","errorClass":"IllegalArgumentException","httpStatus":null,"severity":"error","filePath":"pkl-executor/src/main/java/org/pkl/executor/EmbeddedExecutor.java","lineNumber":204,"sourceCode":"\n    /**\n     * @throws IllegalArgumentException if the Jar file does not exist or is not a valid Pkl\n     *     distribution\n     */\n    PklDistribution(Path pklFatJar, ClassLoader pklExecutorClassLoader) {\n      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;","sourceCodeStart":186,"sourceCodeEnd":222,"githubUrl":"https://github.com/apple/pkl/blob/f3efcbfc9b60d30053b0536d664948d7aa1b8673/pkl-executor/src/main/java/org/pkl/executor/EmbeddedExecutor.java#L186-L222","documentation":"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.","triggerScenarios":"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.","commonSituations":"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.","solutions":["Use the official pkl fat jar as the distribution jar","Verify the jar contains META-INF/services/org.pkl.executor.ExecutorSpi (unzip -l)","Fix shading/assembly configs (e.g. ServicesResourceTransformer) that strip service files","Ensure the jar's Pkl version provides the ExecutorSpi interface"],"exampleFix":"// before\nnew PklDistribution(Path.of(\"app-libs.jar\"), cl); // wrong jar\n// after\nnew PklDistribution(Path.of(\"pkl-0.27.2-fat.jar\"), cl);","handlingStrategy":"validation","validationCode":"try (var zf = new ZipFile(jar.toFile())) {\n  if (zf.getEntry(\"META-INF/services/org.pkl.executor.ExecutorSpi\") == null)\n    throw new IllegalStateException(jar + \" is not a Pkl distribution (no ExecutorSpi service)\");\n}\n","typeGuard":"boolean isPklDistributionJar(Path jar) throws IOException { try (var zf = new ZipFile(jar.toFile())) { return zf.getEntry(\"META-INF/services/org.pkl.executor.ExecutorSpi\") != null; } }\n","tryCatchPattern":"try { new PklDistribution(jar, cl); } catch (IllegalArgumentException e) { if (e.getMessage().contains(\"Cannot find service\")) { /* wrong jar */ } throw e; }\n","preventionTips":["Only point the executor at official pkl fat jars","Preserve META-INF/services in shading (ServicesResourceTransformer)","Verify service entries after any repackaging","Test distribution loading at application startup"],"tags":["pkl","jar","serviceloader","configuration"],"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-14T16:17:12.679Z"}