apple/pkl · error · VmException

jsonParseError

jsonParseError

Error message

jsonParseError

What it means

Pkl's `json.parse(...)` throws `jsonParseError` when the built-in JSON parser (org.pkl.core.util.json.JsonParser) rejects the input text as invalid JSON. The underlying ParseException message is attached as a hint, e.g. expected value, unexpected token, or trailing characters. This is Pkl's standard stdlib behavior: any JSON syntax violation in the string handed to `json.parse` becomes an evalError.

Source

Thrown at pkl-core/src/main/java/org/pkl/core/stdlib/json/ParserNodes.java:62

    }

    @Specialization
    @TruffleBoundary
    protected Object eval(
        VmTyped self, VmTyped resource, @Cached("create()") IndirectCallNode callNode) {
      var text = (String) VmUtils.readMember(resource, Identifier.TEXT, callNode);
      return doParse(self, text);
    }

    private Object doParse(VmTyped self, String text) {
      var converter = PklConverter.fromParser(self);
      var useMapping = (boolean) VmUtils.readMember(self, Identifier.USE_MAPPING);
      var handler = new Handler(converter, useMapping);
      var parser = new JsonParser(handler);
      try {
        parser.parse(text);
      } catch (ParseException e) {
        throw exceptionBuilder().evalError("jsonParseError").withHint(e.getMessage()).build();
      }
      return converter.convert(handler.value, List.of(VmValueConverter.TOP_LEVEL_VALUE));
    }
  }

  private static class Handler
      extends JsonHandler<EconomicMap<Object, ObjectMember>, EconomicMap<Object, ObjectMember>> {
    private final PklConverter converter;
    private final boolean useMapping;

    private final Deque<Object> currPath = new ArrayDeque<>();

    @LateInit private Object value;

    public Handler(PklConverter converter, boolean useMapping) {
      this.converter = converter;
      this.useMapping = useMapping;

View on GitHub (pinned to f3efcbfc9b)

Solutions

1. Validate the JSON text with an external JSON validator or `json.parse` in a scratch script to locate the syntax problem via the error hint
2. Check that the source file/response you are parsing is complete and actually JSON (correct file, no HTML error page)
3. Fix the specific syntax issue named in the hint (quote keys, remove trailing commas, replace single quotes)
4. If the input may be invalid, wrap parsing in your own error handling: decode JSON on the producing side instead of a raw string

Example fix

// before
text: String = read("*.json")
render(text)
// after
x = json.parse(text)

function isValidJson(text: String): Boolean {
  try { json.parse(text); return true } catch (e) { return false }
}

try {
  value = json.parse(text)
} catch (e: PklException) {
  trace("JSON parse failed: ${e.message}")
  // fallback or rethrow with context
}

When it happens

Trigger: Calling `json.parse(text)` where `text` is malformed JSON: truncated input, unquoted or single-quoted keys/strings, trailing commas, JavaScript literals (undefined, NaN), or non-JSON content (HTML, CSV) passed by mistake. Raised in ParserNodes.doParse after JsonParser.parse throws ParseException.

Common situations: Reading JSON from a file or HTTP response that is actually an error page or truncated download; hand-edited JSON with a missing comma or quote; passing a Pkl string interpolation result that contains YAML or XML instead of JSON.

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

• yamlParseError
• Values of type `Duration` cannot be rendered as JSON. Value:
• Values of type `DataSize` cannot be rendered as JSON. Value:
• Values of type `Bytes` cannot be rendered as JSON. Value: %s
• Maps containing non-String keys cannot be rendered as JSON.

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