{"record":{"id":"106188f0d481820a","repo":"json-path/JsonPath","slug":"an-array-or-object-instance-is-expected","errorCode":null,"errorMessage":"an array or object instance is expected","messagePattern":"an array or object instance is expected","errorType":"exception","errorClass":"UnsupportedOperationException","httpStatus":null,"severity":"error","filePath":"json-path/src/main/java/com/jayway/jsonpath/spi/json/JakartaJsonProvider.java","lineNumber":304,"sourceCode":"        List<Object> values;\r\n        if (isArray(obj)) {\r\n            if (obj instanceof JsonArrayBuilder) {\r\n                obj = ((JsonArrayBuilder) obj).build();\r\n            }\r\n            values = new ArrayList<Object>(((List<?>) obj).size());\r\n            for (Object val : ((List<?>) obj)) {\r\n                values.add(unwrap(val));\r\n            }\r\n        } else if (isMap(obj)) {\r\n            if (obj instanceof JsonObjectBuilder) {\r\n                obj = ((JsonObjectBuilder) obj).build();\r\n            }\r\n            values = new ArrayList<Object>(((JsonObject) obj).size());\r\n            for (JsonValue val : ((JsonObject) obj).values()) {\r\n                values.add(unwrap(val));\r\n            }\r\n        } else {\r\n            throw new UnsupportedOperationException(\"an array or object instance is expected\");\r\n        }\r\n        return values;\r\n    }\r\n\r\n    @Override\r\n    public Object unwrap(Object obj) {\r\n        if (obj == null) {\r\n            return null;\r\n        }\r\n        if (!(obj instanceof JsonValue)) {\r\n            return obj;\r\n        }\r\n        switch (((JsonValue) obj).getValueType()) {\r\n        case ARRAY:\r\n        \tif (mutableJson && obj instanceof JsonArrayProxy) {\r\n        \t\treturn (JsonArray) obj;\r\n        \t} else {\r\n        \t\treturn ((JsonArray) obj).getValuesAs((JsonValue v) -> unwrap(v));\r","sourceCodeStart":286,"sourceCodeEnd":322,"githubUrl":"https://github.com/json-path/JsonPath/blob/62a4c9f0f65ba3f625aa0867d64c528ba72d09ec/json-path/src/main/java/com/jayway/jsonpath/spi/json/JakartaJsonProvider.java#L286-L322","documentation":"JakartaJsonProvider.toIterable() converts a JSON value into an Iterable of unwrapped Java objects. It only supports JsonArray (or JsonArrayBuilder) and JsonObject (or JsonObjectBuilder) inputs; anything else — a scalar string, number, boolean, or null — triggers UnsupportedOperationException('an array or object instance is expected'). The library throws it because iteration is only defined over the two JSON container types.","triggerScenarios":"Evaluating a JsonPath (e.g. with JsonPath.using(JakartaJsonProvider...).read(path)) whose result is a scalar like '$.name' or '$' pointing at a string/number/boolean/null, then iterating the result; calling toIterable(obj) directly with a non-container value; applying wildcard/deep-scan paths whose provider internals call toIterable on a leaf node.","commonSituations":"Paths written expecting an array but the document actually holds a scalar (API changed shape); reading '$.field' instead of '$.field[*]'; a null JSON value being iterated; using the Jakarta EE JSON-P provider against documents where the target of the path is a primitive.","solutions":["Check the actual type of the path result first (obj instanceof JsonArray || obj instanceof JsonObject, or use provider.isArray/isMap) before iterating","Adjust the JsonPath to select a container, e.g. use '$.field[*]' or '$.field.arrayProperty' instead of a scalar property","Catch UnsupportedOperationException and treat the value as a scalar: wrap it in a single-element list instead of iterating","If the value is legitimately nullable, guard null before calling paths that force iteration"],"exampleFix":"// before\nIterable<Object> vals = JsonPath.parse(json).read(\"$.items\"); // $.items is \"foo\"\n// after\nObject res = JsonPath.parse(json).read(\"$.items\");\nIterable<Object> vals = (res instanceof List || res instanceof Map)\n    ? JsonPath.parse(json).read(\"$.items\")\n    : java.util.Collections.singletonList(res);","handlingStrategy":"type-guard","validationCode":"// Java\nprivate static boolean isIterableContainer(Object obj) {\n    return obj instanceof List || obj instanceof Map || obj instanceof JsonArray || obj instanceof JsonObject;\n}","typeGuard":"if (obj instanceof JsonArray || obj instanceof JsonArrayBuilder || obj instanceof JsonObject || obj instanceof JsonObjectBuilder) {\n    // safe to iterate via provider.toIterable(obj)\n} else {\n    // treat as scalar: singletonList(obj)\n}","tryCatchPattern":"try {\n    Iterable<?> it = provider.toIterable(obj);\n} catch (UnsupportedOperationException e) {\n    Iterable<?> it = Collections.singletonList(obj);\n}","preventionTips":["Prefer wildcard paths ($.items[*]) so results are always arrays","Inspect getValueType() on JsonValue results before iterating","When reading scalars, use read(path, Class) instead of iterating","Centralize path reading behind a helper that normalizes scalars to lists"],"tags":["json","json-path","unsupported-operation","json-p-provider"],"backgroundTag":"unsupported-operation","analyzedSha":"62a4c9f0f65ba3f625aa0867d64c528ba72d09ec","analyzedAt":"2026-09-11T11:36:00.448Z","contentChangedAt":"2026-09-11T11:36:00.448Z","schemaVersion":2},"datasetVersion":"2026-09-14T05:17:10.506Z"}