{"record":{"id":"4c99d751e0a81293","repo":"apple/pkl","slug":"incompatiblepklversion","errorCode":"incompatiblePklVersion","errorMessage":"incompatiblePklVersion","messagePattern":"incompatiblePklVersion","errorType":"error_code","errorClass":"VmException","httpStatus":null,"severity":"error","filePath":"pkl-core/src/main/java/org/pkl/core/runtime/MinPklVersionChecker.java","lineNumber":90,"sourceCode":"        Version version;\n        try {\n          version = Version.parse(versionText.substring(1, versionText.length() - 1));\n        } catch (IllegalArgumentException e) {\n          return;\n        }\n\n        doCheck(moduleName, version, importNode);\n        return;\n      }\n    }\n  }\n\n  private static void doCheck(\n      String moduleName, @Nullable Version requiredVersion, @Nullable Node importNode) {\n    if (requiredVersion == null || currentMajorMinorPatchVersion.compareTo(requiredVersion) >= 0)\n      return;\n\n    throw new VmExceptionBuilder()\n        .withOptionalLocation(importNode)\n        .evalError(\"incompatiblePklVersion\", moduleName, requiredVersion, currentVersion)\n        .build();\n  }\n\n  private static @Nullable String getLastIdText(@Nullable Type type) {\n    if (!(type instanceof DeclaredType declType)) return null;\n    var identifiers = declType.getName().getIdentifiers();\n    return identifiers.get(identifiers.size() - 1).getValue();\n  }\n}\n","sourceCodeStart":72,"sourceCodeEnd":102,"githubUrl":"https://github.com/apple/pkl/blob/f3efcbfc9b60d30053b0536d664948d7aa1b8673/pkl-core/src/main/java/org/pkl/core/runtime/MinPklVersionChecker.java#L72-L102","documentation":"MinPklVersionChecker.doCheck throws incompatiblePklVersion when a module declares `minPklVersion` greater than the currently running Pkl version. The comparison uses the current major.minor.patch version against the required version, and the error reports the module name, required version, and current version. It is a deliberate compatibility gate, not a failure of the module itself.","triggerScenarios":"Importing/evaluating a module whose `minPklVersion = \"X.Y.Z\"` property exceeds the interpreter's version; doCheck is invoked from check() during module load when the import graph contains such a module.","commonSituations":"Running an older Pkl CLI or embedded runtime against modules written for a newer Pkl release; CI pins an old Pkl version while dependencies bump minPklVersion; a dependency library raised its minPklVersion.","solutions":["Upgrade the Pkl CLI/runtime to at least the required version named in the error message.","If you cannot upgrade, pin the offending dependency to a version whose minPklVersion is compatible.","If you own the module, lower `minPklVersion` only if you truly use no newer-language features."],"exampleFix":"// before (shell)\npkl eval script.pkl  # with Pkl 0.26 but module requires 0.27\n// after\npkl --version  # upgrade first, e.g. via package manager\npkl eval script.pkl","handlingStrategy":"validation","validationCode":"// shell pre-check\npkl --version | awk -v req=\"0.27.0\" -F. 'exit ($2*10000+$3*100+$4 < req ? 1 : 0)' || echo \"upgrade Pkl\"","typeGuard":null,"tryCatchPattern":"try {\n  evaluator.evaluate(moduleSource)\n} catch (e: PklException) {\n  if (e.message?.contains(\"minPklVersion\") == true) fail(\"upgrade Pkl: \" + e.message)\n  throw e\n}","preventionTips":["Pin the Pkl CLI version in CI to at least every dependency's minPklVersion","Check minPklVersion before evaluating third-party modules","Automate dependency bumps with version-gate checks"],"tags":["pkl","version-compatibility","min-pkl-version","upgrade"],"backgroundTag":"incompatible-pkl-version","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"}