json-path/JsonPath · error · IllegalArgumentException

Invalid array index

Error message

Invalid array index

What it means

JakartaJsonProvider.toArrayIndex() normalizes an index argument to Integer for array element access. When the supplied index is null — meaning no usable index was provided by the path evaluation — it throws IllegalArgumentException('Invalid array index'). It is an internal guard reached via setProperty and index when a path component cannot be resolved to a concrete array position.

Source

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

            return Boolean.FALSE;
        case NULL:
            return null;
        default:
            return obj;
        }
    }

    private Integer toArrayIndex(Object index) {
        try {
        	if (index instanceof Integer) {
        		return (Integer) index;
        	} else if (index instanceof Long) {
        		return Integer.valueOf(((Long) index).intValue());
        	} else if (index != null) {
        		return Integer.valueOf(index.toString());
        	} else {
        		//return null;
				throw new IllegalArgumentException("Invalid array index");
            }
        } catch (NumberFormatException e) {
            throw new JsonPathException(e);
        }
    }

    private JsonValue wrap(Object obj) {
        if (obj == null) {
            return JsonValue.NULL;
        } else if (obj instanceof JsonArray) {
        	if (!mutableJson || obj instanceof JsonArrayProxy) {
        		return (JsonArray) obj;
        	} else {
        		return proxyAll((JsonArray) obj);
        	}
        } else if (obj instanceof JsonObject) {
        	if (!mutableJson || obj instanceof JsonObjectProxy) {
        		return (JsonObject) obj;

View on GitHub (pinned to 62a4c9f0f6)

Solutions

1. Ensure the array index passed to JsonPath.set/put (or mapProperty) is a non-null Integer or numeric string
2. Validate the target array length before mutating: provider.length(array) > index
3. Catch IllegalArgumentException/JsonPathException around mutations and handle the missing-index case explicitly
4. Use JakartaJsonProvider.setArrayIndex with a concrete int index rather than path fragments that may resolve to null

Example fix

// before
path.set(document, "$[idx].name", "x"); // idx may be null
// after
Integer idx = resolveIndexOrNull();
if (idx != null && idx < provider.length(JsonPath.parse(document).read("$"))) {
    provider.setArrayIndex(JsonPath.parse(document).read("$"), idx, provider.wrap("x"));
}

// Java
if (index == null) throw new IllegalArgumentException("Array index required");
if (!(index instanceof Integer) && !(index instanceof Long) && !index.toString().matches("-?\\d+"))
    throw new IllegalArgumentException("Index must be numeric: " + index);

boolean isValidIndex(Object idx) {
    return idx instanceof Integer || (idx instanceof Long)
        || (idx != null && idx.toString().matches("-?\\d+"));
}

try {
    provider.setProperty(target, "[" + idx + "]", value);
} catch (IllegalArgumentException | JsonPathException e) {
    // handle missing/invalid index: log and skip or throw domain error
}

When it happens

Trigger: Calling setProperty/mapProperty on an array element with a null or non-numeric key, e.g. path fragments like '$[x]' where the filter yields no index; using JsonPath.set/put API with an index key that evaluates to null; non-numeric string indexes like '$[abc]' reach the same throw via Integer.valueOf(index.toString()) inside the try block only if NumberFormatException — pure null always throws here.

Common situations: Building paths programmatically where a placeholder index was never substituted; JSON documents whose array is shorter than expected so the resolver passes null; typos in inline array indexes when mutating documents with the JsonPath.set API.

Understand the failure class

Background: "Must be a positive integer", "Invalid value", "Unsupported": the invalid-argument-value error family, when a library rejects the value you pass — this error's family across 35 libraries.

Related errors

• Can only add to an array
• Can only add properties to a map
• Add can not be performed to multiple properties
• String.format(message, values)
• Could not find matching close quote for %s when parsing : %s

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