apple/pkl · error · VmException

VmUtils.toVmException(e, source, REPL_TEXT)

Error message

VmUtils.toVmException(e, source, REPL_TEXT)

What it means

In the REPL, expressions typed at the prompt are parsed with Parser.parseExpressionInput; if that fails, the ParserError is converted to a PklException with the REPL pseudo-source and REPL_TEXT as module name. It means the entered text is not a valid standalone Pkl expression.

Solutions

1. Fix the expression so it is a single valid Pkl expression (declarations must be entered differently).
2. Check for unbalanced parentheses/brackets or trailing tokens.
3. Wrap declarations: use the REPL's dedicated declaration input mode rather than expression mode.
4. Test the expression in a scratch .pkl file (`x = <expr>`) to isolate the syntax problem.

Example fix

// before (REPL input)
foo = 1 +
// after
foo = 1 + 2

// Sanity-check REPL input before sending
if (input.trim().isEmpty() || input.contains("\n\n")) { /* prompt user to simplify */ }

try {
  repl.evaluate(input);
} catch (PklException e) {
  System.err.println("Invalid expression: " + e.getMessage());
}

When it happens

Trigger: Typing an incomplete or invalid expression into the Pkl REPL, or programmatic callers of the REPL expression-parsing helper passing malformed input.

Common situations: Pasting multi-statement or declaration-only code (e.g. class or module definitions) where only an expression is allowed; unclosed brackets; using syntax valid in modules but not in expression position.

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

• '" + ch + "'
• closingStringDelimiterMustBeginOnNewLine
• closingStringDelimiterMustBeginOnNewLine
• ':'
• ErrorMessages.create(errorKey, args)

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

Appendix: source

Thrown at pkl-core/src/main/java/org/pkl/core/runtime/VmUtils.java:977

    for (var line = startLine; line <= endLine; line++) {
      sourceLines.add(section.getSource().getCharacters(line).toString());
    }

    return new StackFrame(
        moduleUri,
        memberName,
        sourceLines,
        startLine,
        section.getStartColumn(),
        endLine,
        section.getEndColumn());
  }

  private static Expr parseExpressionNode(String expression, Source source) {
    try {
      return new Parser().parseExpressionInput(expression);
    } catch (ParserError e) {
      throw VmUtils.toVmException(e, source, REPL_TEXT);
    }
  }

  /**
   * Create a fake module that declares all the local properties that exist in {@code module}, so
   * that AstBuilder can correctly resolve variables.
   *
   * <p>Additionally, return a {@link org.pkl.parser.syntax.Node} with its span calculated in terms
   * of this fake module.
   *
   * <p>This created module is never executed.
   */
  public static Pair<String, org.pkl.parser.syntax.Node> buildSyntheticModuleText(
      org.pkl.parser.syntax.Node syntaxNode, VmTyped module, String srcText) {
    if (syntaxNode instanceof ModuleDecl) {
      return Pair.of(srcText, syntaxNode);
    }
    var sb = new StringBuilder();

View on GitHub (pinned to f3efcbfc9b)