json-path/JsonPath · error · PathNotFoundException

Filter: %s can only be applied to arrays. Current context is

Error message

Filter: %s can only be applied to arrays. Current context is: %s

What it means

JsonPath's filter token `[?(...)]` was evaluated against a JSON model that is not an array (e.g. an object or scalar). The library only applies filters to arrays; when the upstream path is definite (cannot yield multiple results) and exceptions are not suppressed, it throws PathNotFoundException instead of returning nothing. It is thrown from checkArrayModel during path evaluation, not compilation.

Source

Thrown at json-path/src/main/java/com/jayway/jsonpath/internal/path/ArrayPathToken.java:48

     * @return false if current evaluation call must be skipped, true otherwise
     * @throws PathNotFoundException if model is null and evaluation must be interrupted
     * @throws InvalidPathException if model is not an array and evaluation must be interrupted
     */
    protected boolean checkArrayModel(String currentPath, Object model, EvaluationContextImpl ctx) {
        if (model == null){
            if (!isUpstreamDefinite()
                    || ctx.options().contains(Option.SUPPRESS_EXCEPTIONS)) {
                return false;
            } else {
                throw new PathNotFoundException("The path " + currentPath + " is null");
            }
        }
        if (!ctx.jsonProvider().isArray(model)) {
            if (!isUpstreamDefinite()
                    || ctx.options().contains(Option.SUPPRESS_EXCEPTIONS)) {
                return false;
            } else {
                throw new PathNotFoundException(format("Filter: %s can only be applied to arrays. Current context is: %s", toString(), model));
            }
        }
        return true;
    }
}

View on GitHub (pinned to 62a4c9f0f6)

Solutions

1. Verify the value the filter is applied to is actually a JSON array (inspect with JsonPath.read up to the filter without it).
2. Wrap the filter target in an array-ifying expression, e.g. `$.items.values()` or use `$[?(@.x)]` only after a wildcard/scan that yields arrays.
3. Add Option.SUPPRESS_EXCEPTIONS (or Option.ALWAYS_RETURN_LIST) to the Configuration so a non-array context returns empty/null instead of throwing.
4. If the source data changed shape, update the path to address the array (e.g. `$.store.book[?(...)]` instead of `$.store[?(...)]`).

Example fix

// before
List<Map<String,Object>> cheap = JsonPath.read(json, "$[?(@.price < 10)]"); // json root is an object
// after
List<Map<String,Object>> cheap = JsonPath.read(json, "$.items[?(@.price < 10)]");
// or suppress:
Configuration cfg = Configuration.builder().options(Option.SUPPRESS_EXCEPTIONS).build();

Object ctxVal = JsonPath.read(json, "$.store");
if (!(ctxVal instanceof List)) {
    throw new IllegalArgumentException("Filter target '$.store' is not an array: " + (ctxVal == null ? "null" : ctxVal.getClass()));
}

boolean isArrayContext(Object model) {
    return model instanceof java.util.List;
}

try {
    return JsonPath.read(json, "$.store[?(@.price < 10)]");
} catch (PathNotFoundException e) {
    return java.util.Collections.emptyList();
}

When it happens

Trigger: Evaluating a path like `$.store[?(@.price < 10)]` where `$.store` resolves to an object or null rather than an array; calling JsonPath.read with a filter on a definite path whose value is a map; compiling with a filter after a property access that returns a single object.

Common situations: Document schema drift: an API starts returning a single object where a list used to be; typos in property names resolving to null; forgetting that `$..prop[?(...)]` upstream may be non-array on some documents; users assuming filters work on objects like in jq.

Understand the failure class

Background: 'Could not be found', 'does not exist', 'not found in database': the resource-not-found family when an ID, slug, key, or URI lookup comes back empty — this error's family across 20 libraries.

Related errors

• No results for path:
• No results for path:
• Missing property in path
• The path is null
• Not enough predicates supplied for filter [] at position

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