{"record":{"id":"a7cbfc0531341d02","repo":"apple/pkl","slug":"pkl-module-s-does-not-state-which-pkl-version-i","errorCode":null,"errorMessage":"Pkl module `%s` does not state which Pkl version it requires. (Available versions: %s)%nTo fix this problem, annotate the module's `amends`, `extends`, or `module` clause with `@ModuleInfo { minPklVersion = \"x.y.z\" }`.","messagePattern":"Pkl module `(.+?)` does not state which Pkl version it requires\\. \\(Available versions: (.+?)\\)%nTo fix this problem, annotate the module's `amends`, `extends`, or `module` clause with `@ModuleInfo (.+?)`\\.","errorType":"exception","errorClass":"ExecutorException","httpStatus":null,"severity":"error","filePath":"pkl-executor/src/main/java/org/pkl/executor/EmbeddedExecutor.java","lineNumber":126,"sourceCode":"  private Version detectRequestedPklVersion(Path modulePath, ExecutorOptions options) {\n    String sourceText;\n    try {\n      sourceText = Files.readString(modulePath, StandardCharsets.UTF_8);\n    } catch (IOException e) {\n      throw new ExecutorException(\n          String.format(\"I/O error loading Pkl module `%s`.\", toDisplayPath(modulePath, options)),\n          e);\n    }\n\n    var version = extractMinPklVersion(sourceText);\n    if (version != null) return version;\n\n    var availableVersions =\n        pklDistributions.stream()\n            .map(it -> it.getVersion().toString())\n            .collect(Collectors.joining(\", \"));\n\n    throw new ExecutorException(\n        String.format(\n            \"Pkl module `%s` does not state which Pkl version it requires. (Available versions: %s)%n\"\n                + \"To fix this problem, annotate the module's `amends`, `extends`, or `module` clause with `@ModuleInfo { minPklVersion = \\\"x.y.z\\\" }`.\",\n            toDisplayPath(modulePath, options), availableVersions));\n  }\n\n  static @Nullable Version extractMinPklVersion(String sourceText) {\n    var matcher = MODULE_INFO_PATTERN.matcher(sourceText);\n    return matcher.find() ? Version.parse(matcher.group(1)) : null;\n  }\n\n  private PklDistribution findCompatibleDistribution(\n      Path modulePath, Version requestedVersion, ExecutorOptions options) {\n    var result =\n        pklDistributions.stream()\n            .filter(it -> it.getVersion().compareTo(requestedVersion) >= 0)\n            .min(Comparator.comparing(PklDistribution::getVersion));\n","sourceCodeStart":108,"sourceCodeEnd":144,"githubUrl":"https://github.com/apple/pkl/blob/f3efcbfc9b60d30053b0536d664948d7aa1b8673/pkl-executor/src/main/java/org/pkl/executor/EmbeddedExecutor.java#L108-L144","documentation":"After reading the module, detectRequestedPklVersion could not find a required Pkl version: the module has no @ModuleInfo { minPklVersion = ... } annotation on its amends/extends/module clause and extractMinPklVersion returned null. Because the embedded executor supports multiple Pkl distributions, it refuses to guess which version to use, listing the available versions instead.","triggerScenarios":"Evaluating a module whose header clause (amends/extends/module) lacks the @ModuleInfo { minPklVersion } annotation while multiple pklDistributions are configured, via evaluatePath.","commonSituations":"Older modules written before @ModuleInfo existed; modules copied/generated without the annotation; teams upgrading to a multi-version embedded executor setup.","solutions":["Add @ModuleInfo { minPklVersion = \"x.y.z\" } to the module's amends, extends, or module clause","Use the versions listed in the error message to pick a valid minPklVersion","If your tooling generates modules, emit the annotation in the template"],"exampleFix":"// before\namends \"pkl:base\"\n\n// after\n@ModuleInfo { minPklVersion = \"0.25.0\" }\namends \"pkl:base\"","handlingStrategy":"validation","validationCode":"String text = Files.readString(modulePath);\nif (!text.contains(\"@ModuleInfo\")) throw new IllegalArgumentException(modulePath + \" missing @ModuleInfo minPklVersion\");\n","typeGuard":"boolean declaresMinPklVersion(String src) { return src.contains(\"@ModuleInfo\") && src.contains(\"minPklVersion\"); }\n","tryCatchPattern":"try { executor.evaluatePath(p, options); } catch (ExecutorException e) { if (e.getMessage().contains(\"does not state which Pkl version\")) { /* prompt to add annotation */ } throw e; }\n","preventionTips":["Add @ModuleInfo { minPklVersion } to every module template","Lint modules in CI for the annotation","Document the annotation requirement in CONTRIBUTING","Pick minPklVersion from the executor's configured distributions"],"tags":["pkl","versioning","configuration"],"backgroundTag":"missing-required-config-field","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"}