apple/pkl · error · VmException

VmUtils.toVmException(e, source, moduleName)

Error message

VmUtils.toVmException(e, source, moduleName)

What it means

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.

Source

Thrown at pkl-core/src/main/java/org/pkl/core/runtime/VmLanguage.java:107

            importNode);
  }

  void initializeModule(
      ModuleKey moduleKey,
      ResolvedModuleKey resolvedModuleKey,
      ModuleResolver moduleResolver,
      Source source,
      VmTyped emptyModule,
      @Nullable Node importNode) {
    var parser = new Parser();
    Module moduleContext;
    var sourceStr = source.getCharacters().toString();
    try {
      moduleContext = parser.parseModule(sourceStr);
    } catch (ParserError e) {
      var moduleName = IoUtils.inferModuleName(moduleKey);
      MinPklVersionChecker.check(moduleName, e.getPartialParseResult(), importNode, sourceStr);
      throw VmUtils.toVmException(e, source, moduleName);
    }

    var builder =
        AstBuilder.create(
            source, this, moduleContext, moduleKey, resolvedModuleKey, moduleResolver);
    var moduleNode = builder.visitModule(moduleContext);
    moduleNode.getCallTarget().call(emptyModule, emptyModule);
    MinPklVersionChecker.check(emptyModule, importNode);
  }
}

View on GitHub (pinned to f3efcbfc9b)

Solutions

1. Fix the syntax error at the span shown in the exception message.
2. If MinPklVersionChecker flags it, upgrade your Pkl runtime/CLI to at least the module's declared min version.
3. Pin module dependencies to versions compatible with your Pkl runtime.
4. Run `pkl --version` and compare against the module's `min-pkl-version` annotation.

Example fix

// before (build.gradle)
"org.pkl-lang:pkl-config-java:0.25.0" // too old for module requiring 0.27
// after
"org.pkl-lang:pkl-config-java:0.27.1"

// Check declared min version before initializing
String minPklVersion = extractMinPklVersionAnnotation(sourceStr);
if (minPklVersion != null && compare(runningPklVersion, minPklVersion) < 0) {
  throw new IllegalStateException("Pkl " + minPklVersion + " required, running " + runningPklVersion);
}

try {
  evaluator.evalOutput(source);
} catch (PklException e) {
  if (e.getMessage().contains("pkl version")) {
    throw new IllegalStateException("Upgrade Pkl runtime: " + e.getMessage(), e);
  }
  throw e;
}

When it happens

Trigger: 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.

Common situations: 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.

Related errors

• VmUtils.toVmException(e, source, moduleName)
• resourceNotInAllowList|moduleNotInAllowList
• Is a directory
• incompatiblePklVersion
• cannotEvaluateNonFileBasedTestModule

AI-assisted analysis of apple/pkl@f3efcbfc9b (2026-09-08). Data as JSON: /api/errors/acbec6bfee79df99. Report an issue: GitHub.