What causes "Invalid literal — expected 'null'" in karatelabs/karate?

Replace the literal with lowercase 'null'.

Invalid literal — expected 'null'

Error message

Invalid literal — expected 'null'

What it means

JSON literal parsing error in parseNull: the parser saw a token starting like 'null' but the following characters did not spell it out completely. Fires on malformed input such as 'nul' or 'nulx'; fix the literal spelling.

Solutions

Replace the literal with lowercase 'null'.
Serialize with a JSON-aware encoder that maps None/NULL/nil to null.
Omit the key entirely if the intent is 'absent' rather than emitting a language-specific null.
Check for truncation if the token is a prefix of 'null'.

Example fix

// before
String json = "{\"user\": None}"; // Python str()
// after
String json = "{\"user\": null}"; // json.dumps handles this

Defensive patterns

Strategy: validation

Validate before calling

// normalize language-specific nulls before parsing
raw = raw.replaceAll("\\b(None|NULL|nil|undefined)\\b", "null");
// or omit absent keys entirely instead of emitting a null placeholder

Try / catch

// Java
try {
    Json json = Json.of(raw);
} catch (Exception e) {
    if (String.valueOf(e.getMessage()).contains("expected 'null'")) {
        raw = raw.replaceAll("\\b(None|NULL|nil)\\b", "null");
    } else { throw e; }
}

Prevention

Only the exact lowercase literal 'null' is valid JSON.
Map None/NULL/nil through a JSON serializer, never string interpolation.
Omit keys for absent values instead of emitting language-specific nulls.
Check truncation if the token is a prefix like 'nul'.

When it happens

Trigger: Parsing JSON containing 'NULL' (SQL exports), 'None' (Python), 'nil'/'undefined' (other languages), or a truncated '{"x": nul}' where parseValue dispatched to parseNull on a token starting with 'n'.

Common situations: SQL query results dumped to JSON with NULL literals; Python data serialized via str() instead of json.dumps; templating that interpolates language-specific nulls; truncated responses.

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 karatelabs/karate@a22eb90246 (2026-09-12). Data as JSON: /api/errors/04d8d46e471c779d. Report an issue: GitHub.

Appendix: source

Thrown at karate-js/src/main/java/io/karatelabs/js/JsonParser.java:343

                if (pos + 4 <= len && s.charAt(pos + 1) == 'r' && s.charAt(pos + 2) == 'u' && s.charAt(pos + 3) == 'e') {
                    pos += 4;
                    return Boolean.TRUE;
                }
                throw syntaxError("Invalid literal — expected 'true'");
            }
            if (pos + 5 <= len && s.charAt(pos + 1) == 'a' && s.charAt(pos + 2) == 'l' && s.charAt(pos + 3) == 's' && s.charAt(pos + 4) == 'e') {
                pos += 5;
                return Boolean.FALSE;
            }
            throw syntaxError("Invalid literal — expected 'false'");
        }

        private Object parseNull() {
            if (pos + 4 <= len && s.charAt(pos + 1) == 'u' && s.charAt(pos + 2) == 'l' && s.charAt(pos + 3) == 'l') {
                pos += 4;
                return null;
            }
            throw syntaxError("Invalid literal — expected 'null'");
        }

        void skipWs() {
            while (pos < len) {
                char c = s.charAt(pos);
                if (c == ' ' || c == '\t' || c == '\n' || c == '\r') {
                    pos++;
                } else {
                    return;
                }
            }
        }

        JsErrorException syntaxError(String message) {
            return JsErrorException.syntaxError(message + " at position " + pos);
        }

    }

View on GitHub (pinned to a22eb90246)