What causes "Unable to read json constant for: ${expected}" in quarkusio/quarkus?

Replace the literal with the exact lowercase JSON form: true, false, or null

quarkusio/quarkus · error · IllegalArgumentException

Unable to read json constant for: ${expected}

Error message

Unable to read json constant for: ${expected}

What it means

readConstant() parses JSON literals true, false, and null by exact region match. If the text at the current position does not exactly equal the expected literal (e.g. 'tru', 'True', 'nullx'), the literal is malformed and IllegalArgumentException is thrown. It enforces JSON's case-sensitive lowercase literal spelling.

Source

Thrown at independent-projects/bootstrap/json/src/main/java/io/quarkus/bootstrap/json/JsonReader.java:309

        return isFraction;
    }

    private void ignoreDigits() {
        while (position < length) {
            final int ch = peekChar();
            if (!Character.isDigit(ch)) {
                break;
            }
            position++;
        }
    }

    private JsonValue readConstant(String expected, JsonValue result) {
        if (text.regionMatches(position, expected, 0, expected.length())) {
            position += expected.length();
            return result;
        }
        throw new IllegalArgumentException("Unable to read json constant for: " + expected);
    }

    /**
     * ws
     * |---- ""
     * |---- '0020' ws
     * |---- '000A' ws
     * |---- '000D' ws
     * |---- '0009' ws
     */
    private void ignoreWhitespace() {
        while (position < length) {
            final int ch = peekChar();
            switch (ch) {
                case ' ': // '0020' SPACE
                case '\n': // '000A' LINE FEED
                case '\r': // '000D' CARRIAGE RETURN
                case '\t': // '0009' CHARACTER TABULATION

View on GitHub (pinned to e1c734241f)

Solutions

Replace the literal with the exact lowercase JSON form: true, false, or null
Fix the producer to serialize language-native booleans/nulls to JSON correctly (e.g. Python's json module instead of str(True))
Check for stray characters right after the literal and remove them

Example fix

// before
{"flag":True, "value":None}
// after
{"flag":true, "value":null}

Defensive patterns

Strategy: validation

Validate before calling

// Pre-check for non-lowercase JSON literals before parsing
if (jsonText.matches("(?s).*(True|FALSE|None|NULL|undefined).*")) {
    throw new IllegalArgumentException("Non-JSON literal found (use true/false/null)");
}

Try / catch

try {
    JsonValue v = new JsonReader(text).read();
} catch (IllegalArgumentException e) {
    if (e.getMessage().startsWith("Unable to read json constant")) {
        // identify and correct the malformed literal reported in the message
    }
}

Prevention

JSON literals are lowercase only: true, false, null — never True/None/NULL
Use a proper JSON serializer when converting from Python/JS values
Watch for stray characters appended directly after literals (e.g. 'nullx')

When it happens

Trigger: Input contains a misspelled or wrongly-cased literal where a JSON constant is expected: 'True', 'TRUE', 'None', 'tru e', or a literal immediately followed by extra characters, e.g. 'nullx'.

Common situations: Generating JSON from another language's literals (Python True/None, JavaScript undefined); template/serialization bugs appending stray characters after literals; hand-written JSON with capitalized booleans.

Related errors

AI-assisted analysis of quarkusio/quarkus@e1c734241f (2026-09-05). Data as JSON: /api/errors/b6db8f385ec654ce. Report an issue: GitHub.