apple/pkl · error · VmException

VmUtils.toVmException(e, source, moduleName)

Error message

VmUtils.toVmException(e, source, moduleName)

What it means

When scanning a module solely for its imports and `read(...)` expressions, a ParserError from the Pkl parser is converted via VmUtils.toVmException into a PklException carrying the source, module name, and formatted diagnostic. This wraps raw parser errors so they surface with proper file/line/span information to the evaluator caller.

Source

Thrown at pkl-core/src/main/java/org/pkl/core/ast/builder/ImportsAndReadsParser.java:76

      boolean isModule,
      boolean isGlob,
      boolean isExtends,
      boolean isAmends,
      String stringValue,
      SourceSection sourceSection) {}

  /** Parses a module, and collects all imports and reads. */
  public static List<Entry> parse(ModuleKey moduleKey, ResolvedModuleKey resolvedModuleKey)
      throws IOException {
    var parser = new Parser();
    var text = resolvedModuleKey.loadSource();
    var source = VmUtils.createSource(moduleKey, text);
    var importListParser = new ImportsAndReadsParser(source);
    try {
      return parser.parseModule(text).accept(importListParser);
    } catch (ParserError e) {
      var moduleName = IoUtils.inferModuleName(moduleKey);
      throw VmUtils.toVmException(e, source, moduleName);
    }
  }

  public ImportsAndReadsParser(Source source) {
    super(source);
  }

  @Override
  protected VmExceptionBuilder exceptionBuilder() {
    return new VmExceptionBuilder();
  }

  @Override
  public @Nullable List<Entry> visitExtendsOrAmendsClause(ExtendsOrAmendsClause decl) {
    var importStr = decl.getUrl().getString();
    var sourceSection = createSourceSection(decl.getUrl());
    return Collections.singletonList(
        new Entry(

View on GitHub (pinned to f3efcbfc9b)

Solutions

  1. Read the converted VmException message — it contains the span and caret pointing at the syntax error; fix that line in the module.
  2. Verify the moduleKey resolves to actual Pkl source (not an error page or binary).
  3. Confirm the Pkl version used supports the syntax in the module (e.g. new features).
  4. Validate the file standalone with `pkl eval <file>` to reproduce the parse error.

Example fix

// before
ImportGraph.scan(moduleKey, htmlErrorPage)
// after
val text = fetchPklSource(moduleKey) // ensure text/*.pkl content
ImportGraph.scan(moduleKey, text)
Defensive patterns

Strategy: try-catch

Validate before calling

// Verify source is plausibly Pkl before parsing imports
if (!text.contains("module") && !text.contains("=")) throw new IOException("Not Pkl source: " + moduleKey);

Try / catch

try {
  ImportGraph.scan(moduleKey, text);
} catch (PklException e) {
  logger.error("Import scan failed for {}: {}", moduleKey, e.getMessage());
}

Prevention

When it happens

Trigger: Calling the import/read extraction entry point (parser.parseModule(text).accept(importListParser)) on text that is not syntactically valid Pkl for the given moduleKey.

Common situations: Loading a module from a cache or network with truncated/corrupted content; pointing a dependency at a non-Pkl file (HTML error page, YAML); running with an older Pkl version than the module syntax requires.

Understand the failure class

Background: JSON parse error: "Unexpected token" / "not valid JSON" / "failed to parse" — what JSON parsers are really complaining about — this error's family across 45 libraries.

Related errors

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