json-path/JsonPath · error · JsonPathException

length operation can not applied to null

Error message

length operation can not applied to null

What it means

JakartaJsonProvider.length() computes lengths for arrays, maps, JSON values with arrays, and CharSequences; anything else (numbers, booleans, null) causes JsonPathException "length operation can not applied to <class>". It backs JsonPath's .length() function, which is undefined for scalar non-string values.

Source

Thrown at json-path/src/main/java/com/jayway/jsonpath/spi/json/JakartaJsonProvider.java:281

    public int length(Object obj) {
        if (isArray(obj)) {
            if (obj instanceof JsonArrayBuilder) {
                return ((JsonArrayBuilder) obj).build().size();
            } else {
                return ((List<?>) obj).size();
            }
        } else if (isMap(obj)) {
            if (obj instanceof JsonObjectBuilder) {
                obj = ((JsonObjectBuilder) obj).build();
            }
            return ((JsonObject) obj).size();
        } else {
            if (obj instanceof CharSequence) {
                return ((CharSequence) obj).length();
            }
        }
        String className = obj != null ? obj.getClass().getName() : null;
        throw new JsonPathException("length operation can not applied to " + className);
    }

    @Override
    public Iterable<?> toIterable(Object obj) {
        List<Object> values;
        if (isArray(obj)) {
            if (obj instanceof JsonArrayBuilder) {
                obj = ((JsonArrayBuilder) obj).build();
            }
            values = new ArrayList<Object>(((List<?>) obj).size());
            for (Object val : ((List<?>) obj)) {
                values.add(unwrap(val));
            }
        } else if (isMap(obj)) {
            if (obj instanceof JsonObjectBuilder) {
                obj = ((JsonObjectBuilder) obj).build();
            }
            values = new ArrayList<Object>(((JsonObject) obj).size());

View on GitHub (pinned to 62a4c9f0f6)

Solutions

1. Ensure the path expression targets an array, object, or string before applying .length().
2. Guard with a filter or optional evaluation (JsonPath.using(conf).withListeners...) and check for MISSING/undefined results first.
3. Verify the JSON schema: if the field can be null, branch your query accordingly.
4. Catch JsonPathException around length evaluation for defensive handling.

Example fix

// before
int n = JsonPath.read(doc, "$.maybeMissing.length()");
// after
Object node = JsonPath.read(doc, "$.maybeMissing");
int n = (node instanceof List || node instanceof CharSequence) ? JsonPath.read(doc, "$.maybeMissing.length()") : 0;

// Java
Object node = JsonPath.read(doc, path);
boolean lengthSafe = node instanceof List || node instanceof java.util.Map || node instanceof CharSequence;

// Java
static boolean lengthSupported(Object o) {
    return o instanceof List || o instanceof java.util.Map || o instanceof CharSequence;
}

try { return JsonPath.read(doc, path + ".length()"); } catch (JsonPathException e) { return 0; }

When it happens

Trigger: Using the path function length() (e.g. $.items.length() or $.someNumber.length()) where the resolved node is null, a number, or a boolean.

Common situations: Path expressions evaluated against documents where the target is missing (null) or where a field changed type from string/array to number between data versions.

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

• length operation can not applied to null
• length operation can not applied to null
• Can only rename properties in a map
• Can only add to an array
• Can only add properties to a map

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