apple/pkl · error · ParseException
value
Error message
value
What it means
The JSON parser's readValue throws 'value' expected (via expected("value")) when the character at the current position cannot start any JSON value: it must be null/true/false/'"'/'['/'{'/a number. This fires for empty input, or input starting with characters like 'u', 'True', '}', or a bare word. It is the most common JSON syntax failure and appears as the hint of jsonParseError.
Source
Thrown at pkl-core/src/main/java/org/pkl/core/util/json/JsonParser.java:139
read();
skipWhiteSpace();
readValue();
skipWhiteSpace();
if (!isEndOfText()) {
throw error("Unexpected character");
}
}
private void readValue() throws IOException {
switch (current) {
case 'n' -> readNull();
case 't' -> readTrue();
case 'f' -> readFalse();
case '"' -> readString();
case '[' -> readArray();
case '{' -> readObject();
case '-', '0', '1', '2', '3', '4', '5', '6', '7', '8', '9' -> readNumber();
default -> throw expected("value");
}
}
private void readArray() throws IOException {
var array = handler.startArray();
read();
if (++nestingLevel > MAX_NESTING_LEVEL) {
throw error("Nesting too deep");
}
skipWhiteSpace();
if (readChar(']')) {
nestingLevel--;
handler.endArray(array);
return;
}
do {
skipWhiteSpace();
handler.startArrayValue(array);View on GitHub (pinned to f3efcbfc9b)
Solutions
- Check that the input is non-empty before parsing
- Fix the value's spelling: use lowercase true/false/null (not True/False/None)
- Verify you read the file's contents, not its name (e.g. use read() properly in Pkl)
- Validate the JSON externally to find the exact bad character position
Example fix
// before
v = json.parse(flag) // flag = "True"
// after
v = json.parse("true") Defensive patterns
Strategy: validation
Validate before calling
trimmed = text.trim()
require(!trimmed.isEmpty(), "json.parse: input is empty")
require("[{\"tfn0123456789-".contains(trimmed.substring(0, 1)),
"json.parse: input does not start with a JSON value") Try / catch
if (text.trim().isEmpty()) {
value = defaultValue
} else {
value = json.parse(text)
} Prevention
- Always check for empty files/bodies before parsing
- Use lowercase JSON literals: true/false/null
- Verify you pass file contents, not a path string
When it happens
Trigger: Calling `json.parse` on an empty or whitespace-only string, on `True`/`False`/`None` (Python-style literals), on a single unquoted word, or on input starting with `}` or `,`. Raised in JsonParser.readValue's default branch.
Common situations: Reading an empty file (zero bytes) or an HTTP response with empty body; serialized output from a non-JSON serializer (Python repr); path/expansion mistakes producing a filename string instead of file contents.
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/a1f77cecd85f4cc5.
Report an issue: GitHub.