json-path/JsonPath · error · JsonPathException

Cannot iterate over

Error message

Cannot iterate over 

What it means

AbstractJsonProvider.toIterable converts a JSON array into an Iterable so paths can be iterated. Only arrays support iteration; passing any other node type (object, string, number, null) throws JsonPathException. The message also suffers an operator-precedence bug ('+' before '!='), possibly printing wrong class info, but the cause is a non-array target.

Source

Thrown at json-path/src/main/java/com/jayway/jsonpath/spi/json/AbstractJsonProvider.java:171

        } else if(obj instanceof String){
            return ((String)obj).length();
        }
        throw new JsonPathException("length operation cannot be applied to " + (obj != null ? obj.getClass().getName()
                : "null"));
    }

    /**
     * Converts given array to an {@link Iterable}
     *
     * @param obj an array
     * @return an Iterable that iterates over the entries of an array
     */
    @SuppressWarnings("unchecked")
    public Iterable<?> toIterable(Object obj) {
        if (isArray(obj))
            return ((Iterable) obj);
        else
            throw new JsonPathException("Cannot iterate over " + obj!=null?obj.getClass().getName():"null");
    }

    @Override
    public Object unwrap(Object obj) {
        return obj;
    }

}

View on GitHub (pinned to 62a4c9f0f6)

Solutions

1. Ensure the node is an array before iterating (check isArray(obj))
2. Correct the path: use .* or property access for objects instead of [*]
3. Null/type-check the resolved node before iteration and handle the non-array case explicitly
4. Wrap evaluation in try-catch for JsonPathException when document shape is uncertain

Example fix

// before
for (Object o : provider.toIterable(node)) { ... } // throws if node is a Map
// after
if (provider.isArray(node)) {
    for (Object o : provider.toIterable(node)) { ... }
} else if (provider.isMap(node)) {
    for (Object o : provider.getPropertyKeys(node)) { ... }
}

if (!provider.isArray(node)) throw new IllegalArgumentException("expected JSON array, got: " + (node == null ? "null" : node.getClass()));

boolean isArray(Object o) { return o instanceof Iterable; }

try {
    for (Object o : provider.toIterable(node)) { handle(o); }
} catch (JsonPathException e) {
    // node was not an array
}

When it happens

Trigger: Evaluating wildcard/iterate paths like $[*] or $.items[*] where the node is not an array; calling jsonProvider.toIterable(obj) directly on a Map/String; using walk/forEach-style JsonPath APIs over a scalar node.

Common situations: Iterating a field that is an object in some responses and an array in others; iterating null fields; deep-scan ..[*] paths crossing primitive nodes the developer assumed were arrays.

Understand the failure class

Background: UnsupportedOperationException and "is not supported" errors: when a library deliberately refuses a call — this error's family across 30 libraries.

Related errors

• Put can not be performed to multiple properties
• Rename can not be performed to multiple properties
• setProperty operation cannot be used with
• length operation cannot be applied to
• length operation can not applied to

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