{"record":{"id":"acbec6bfee79df99","repo":"apple/pkl","slug":"vmutils-tovmexception-e-source-modulename-acbec6","errorCode":null,"errorMessage":"VmUtils.toVmException(e, source, moduleName)","messagePattern":"VmUtils\\.toVmException\\(e, source, moduleName\\)","errorType":"exception","errorClass":"VmException","httpStatus":null,"severity":"error","filePath":"pkl-core/src/main/java/org/pkl/core/runtime/VmLanguage.java","lineNumber":107,"sourceCode":"            importNode);\n  }\n\n  void initializeModule(\n      ModuleKey moduleKey,\n      ResolvedModuleKey resolvedModuleKey,\n      ModuleResolver moduleResolver,\n      Source source,\n      VmTyped emptyModule,\n      @Nullable Node importNode) {\n    var parser = new Parser();\n    Module moduleContext;\n    var sourceStr = source.getCharacters().toString();\n    try {\n      moduleContext = parser.parseModule(sourceStr);\n    } catch (ParserError e) {\n      var moduleName = IoUtils.inferModuleName(moduleKey);\n      MinPklVersionChecker.check(moduleName, e.getPartialParseResult(), importNode, sourceStr);\n      throw VmUtils.toVmException(e, source, moduleName);\n    }\n\n    var builder =\n        AstBuilder.create(\n            source, this, moduleContext, moduleKey, resolvedModuleKey, moduleResolver);\n    var moduleNode = builder.visitModule(moduleContext);\n    moduleNode.getCallTarget().call(emptyModule, emptyModule);\n    MinPklVersionChecker.check(emptyModule, importNode);\n  }\n}\n","sourceCodeStart":89,"sourceCodeEnd":118,"githubUrl":"https://github.com/apple/pkl/blob/f3efcbfc9b60d30053b0536d664948d7aa1b8673/pkl-core/src/main/java/org/pkl/core/runtime/VmLanguage.java#L89-L118","documentation":"During module initialization, VmLanguage.parseModule compiles the source string; a ParserError is enriched with module name and source via VmUtils.toVmException, and MinPklVersionChecker first checks whether the failure is due to the module requiring a newer Pkl version (its min-pkl-version annotation). The result is a well-formatted PklException with span diagnostics instead of a raw parser error.","triggerScenarios":"Evaluating or importing any module whose source fails to parse: syntax errors, unsupported new syntax on an old Pkl runtime, or a `@minPklVersion` requirement exceeding the running version.","commonSituations":"Using modules from a newer Pkl stdlib/project with an older pkl-cli/dependency; typos in a newly edited config; mixing module versions in dependency resolution.","solutions":["Fix the syntax error at the span shown in the exception message.","If MinPklVersionChecker flags it, upgrade your Pkl runtime/CLI to at least the module's declared min version.","Pin module dependencies to versions compatible with your Pkl runtime.","Run `pkl --version` and compare against the module's `min-pkl-version` annotation."],"exampleFix":"// before (build.gradle)\n\"org.pkl-lang:pkl-config-java:0.25.0\" // too old for module requiring 0.27\n// after\n\"org.pkl-lang:pkl-config-java:0.27.1\"","handlingStrategy":"try-catch","validationCode":"// Check declared min version before initializing\nString minPklVersion = extractMinPklVersionAnnotation(sourceStr);\nif (minPklVersion != null && compare(runningPklVersion, minPklVersion) < 0) {\n  throw new IllegalStateException(\"Pkl \" + minPklVersion + \" required, running \" + runningPklVersion);\n}","typeGuard":null,"tryCatchPattern":"try {\n  evaluator.evalOutput(source);\n} catch (PklException e) {\n  if (e.getMessage().contains(\"pkl version\")) {\n    throw new IllegalStateException(\"Upgrade Pkl runtime: \" + e.getMessage(), e);\n  }\n  throw e;\n}","preventionTips":["Keep the pkl runtime/CLI version aligned with the modules you consume.","Check each module's `@minPklVersion` annotation before adopting it.","Run `pkl eval` on modules in CI to catch parse regressions early."],"tags":["pkl","parser","version-compatibility","module-loading"],"backgroundTag":"module-init-failed","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"}