What causes "Target index: larger than object count:" in json-path/JsonPath?

Verify array length before applying the index, or use functions that tolerate short arrays.

json-path/JsonPath · error · JsonPathException

Target index: larger than object count:

Error message

Target index: larger than object count:

What it means

Sequence functions (first(), last(), index(n), slice()) select an element by index from the target array. When a positive target index exceeds the last position of the list (or the wrapped negative index computation fails), AbstractSequenceAggregation.invoke throws JsonPathException('Target index:N larger than object count:M').

Source

Thrown at json-path/src/main/java/com/jayway/jsonpath/internal/function/sequence/AbstractSequenceAggregation.java:36

    
    protected abstract int targetIndex(EvaluationContext ctx, List<Parameter> parameters);
    
    @Override
    public Object invoke(String currentPath, PathRef parent, Object model, EvaluationContext ctx, List<Parameter> parameters) {
        if(ctx.configuration().jsonProvider().isArray(model)){

            Iterable<?> objects = ctx.configuration().jsonProvider().toIterable(model);
            List<Object> objectList = new ArrayList<>();
            objects.forEach(objectList::add);
            int targetIndex = this.targetIndex(ctx, parameters);
            if (targetIndex >= 0) {
                return objectList.get(targetIndex);
            } else {
                int realIndex = objectList.size() + targetIndex;
                if (realIndex > 0) {
                    return objectList.get(realIndex);
                } else {
                    throw new JsonPathException("Target index:" + targetIndex + " larger than object count:" + objectList.size());
                }
            }
        }
        throw new JsonPathException("Aggregation function attempted to calculate value using empty array");
    }
    
    protected int getIndexFromParameters(EvaluationContext ctx, List<Parameter> parameters) {
        List<Number> numbers = Parameter.toList(Number.class, ctx, parameters);
        return numbers.get(0).intValue();
    }
}

View on GitHub (pinned to 62a4c9f0f6)

Solutions

Verify array length before applying the index, or use functions that tolerate short arrays.
Catch JsonPathException and fall back to a default value for missing positions.
Use index(-1)/last() semantics carefully; negative indices count from the end and can also exceed bounds.
Guard upstream with $[?(@.arr.length() >= N)] filters before selecting.

Example fix

// before
Object v = JsonPath.read(json, "$.readings.index(9)"); // only 3 readings
// after
List<Object> r = JsonPath.read(json, "$.readings");
Object v = (r != null && r.size() > 9) ? r.get(9) : null;

Defensive patterns

Strategy: validation

Validate before calling

List<?> arr = JsonPath.read(json, "$.readings");
Object v = (arr != null && arr.size() > 9) ? arr.get(9) : null;

Try / catch

try {
    return JsonPath.read(json, "$.readings.index(9)");
} catch (JsonPathException e) {
    if (e.getMessage().startsWith("Target index")) return null; // index out of bounds
    throw e;
}

Prevention

Check list size before fixed-index selection
Prefer last()/first() over index(n) when position is relative to the end
Treat array length as variable across environments/documents

When it happens

Trigger: Using functions like $.arr.index(5) or $.arr.first() when the array has fewer elements than the requested index — e.g. index(5) on a 3-element array — via JsonPath.read().

Common situations: Requesting a fixed position from variable-length arrays (e.g. 'always take the 10th sensor reading'), off-by-one assumptions about array size, or documents from different environments having shorter arrays than expected.

Related errors

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