{"record":{"id":"c5de36d1f4b27952","repo":"apple/pkl","slug":"invalid-pkl-distribution-cannot-find-jar-file-s","errorCode":null,"errorMessage":"Invalid Pkl distribution: Cannot find Jar file `%s`.","messagePattern":"Invalid Pkl distribution: Cannot find Jar file `(.+?)`\\.","errorType":"exception","errorClass":"IllegalArgumentException","httpStatus":null,"severity":"error","filePath":"pkl-executor/src/main/java/org/pkl/executor/EmbeddedExecutor.java","lineNumber":193,"sourceCode":"  @Override\n  public void close() throws Exception {\n    for (var pklDistribution : pklDistributions) {\n      pklDistribution.close();\n    }\n  }\n\n  private static final class PklDistribution implements AutoCloseable {\n    final URLClassLoader pklDistributionClassLoader;\n    final ExecutorSpi executorSpi;\n    final Version version;\n\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(","sourceCodeStart":175,"sourceCodeEnd":211,"githubUrl":"https://github.com/apple/pkl/blob/f3efcbfc9b60d30053b0536d664948d7aa1b8673/pkl-executor/src/main/java/org/pkl/executor/EmbeddedExecutor.java#L175-L211","documentation":"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.","triggerScenarios":"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.","commonSituations":"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.","solutions":["Verify Files.isRegularFile(pklFatJar) before constructing","Fix the path to the Pkl fat jar (absolute path is safest)","Ensure the jar is present in the deployment artifact/image","Check CI packaging steps that produce/copy the jar"],"exampleFix":"// before\nvar dist = new PklDistribution(Path.of(\"pkl-cli.jar\"), cl);\n// after\nPath jar = Path.of(\"/opt/pkl/pkl-0.27.2.jar\");\nif (!Files.isRegularFile(jar)) throw new IllegalStateException(\"missing pkl jar: \" + jar);\nvar dist = new PklDistribution(jar, cl);","handlingStrategy":"validation","validationCode":"Path jar = Path.of(distPath);\nif (!Files.isRegularFile(jar)) throw new IllegalStateException(\"pkl fat jar missing: \" + jar);\n","typeGuard":"boolean isValidJarPath(Path p) { return p != null && Files.isRegularFile(p) && p.toString().endsWith(\".jar\"); }\n","tryCatchPattern":"try { new PklDistribution(jar, cl); } catch (IllegalArgumentException e) { throw new ConfigurationException(\"invalid pkl distribution jar\", e); }\n","preventionTips":["Use absolute paths for distribution jars","Verify the jar is copied into container/deployment images","Fail fast at startup with an explicit existence check","Name artifacts predictably in CI"],"tags":["pkl","jar","file-not-found","configuration"],"backgroundTag":"file-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"}