json-path/JsonPath · error · InvalidPathException

Expected null node

Error message

Expected null node

What it means

ValueNode's base asNullNode() throws InvalidPathException("Expected null node") when called on a node that is not a NullNode. NullNode represents a JSON null value in filter evaluation; the base-class default throws because only NullNode can be downcast to itself. It surfaces when an operator or path of evaluation requires a null literal but the operand is some other value type.

Source

Thrown at json-path/src/main/java/com/jayway/jsonpath/internal/filter/ValueNode.java:88

    public PredicateNode asPredicateNode() {
        throw new InvalidPathException("Expected predicate node");
    }

    public boolean isValueListNode() {
        return false;
    }

    public ValueListNode asValueListNode() {
        throw new InvalidPathException("Expected value list node");
    }

    public boolean isNullNode() {
        return false;
    }

    public NullNode asNullNode() {
        throw new InvalidPathException("Expected null node");
    }

    public UndefinedNode asUndefinedNode() {
        throw new InvalidPathException("Expected undefined node");
    }

    public boolean isUndefinedNode() {
        return false;
    }

    public boolean isClassNode() {
        return false;
    }

    public ClassNode asClassNode() {
        throw new InvalidPathException("Expected class node");
    }

View on GitHub (pinned to 62a4c9f0f6)

Solutions

1. Use JsonPath's null-check idioms that tolerate missing values, e.g. $.items[?(@.field == null)] and verify the field exists with @.field in filters where needed
2. Check whether the value is an empty string or 0 rather than null and adjust the comparison accordingly
3. Normalize the document so intended-null fields are actual JSON null
4. Catch InvalidPathException around evaluation for null-mismatch cases

Example fix

// before
$.items[?(@.name == '')] // intended to find null names; name is real null
// after
$.items[?(@.name == null)]

Object v = JsonPath.parse(json).read("$.item.name", new Predicate[0]);
if (v == null && expectNullSentinel) throw new IllegalArgumentException("name is missing, not null");

static boolean isNullOperand(Object o) { return o == null; }

try {
    return JsonPath.parse(json).read("$.items[?(@.name == null)]");
} catch (InvalidPathException e) {
    // null-mismatch: handle absent vs empty vs null distinctly
    return handleNullMismatch(json);
}

When it happens

Trigger: Filter expressions comparing with null semantics where the node is not null — e.g. type checks/operations in evaluate that require NullNode; calling asNullNode() directly on a StringNode/NumberNode. Note: @.field == null in JsonPath is often handled before this, but custom operators or paths that demand a NullNode operand will hit this.

Common situations: Documents where a field checked for null actually holds an empty string, 0, or is missing entirely (undefined), so the operand node is not NullNode; custom filter operators built on the internal API.

Understand the failure class

Background: Type mismatch errors: IllegalArgumentException, TypeError and type guards across 150 open-source libraries — this error's family across 150 libraries.

Related errors

• Expected string node
• Expected boolean node
• Expected json node
• Expected predicate node
• Expected value list node

AI-assisted analysis of json-path/JsonPath@62a4c9f0f6 (2026-09-11). Data as JSON: /api/errors/e6736c04f4d4fbda. Report an issue: GitHub.