{"record":{"id":"af00d6c5912e2251","repo":"json-path/JsonPath","slug":"json-array-cannot-be-mapped-to-classname","errorCode":null,"errorMessage":"JSON array cannot be mapped to \" + className","messagePattern":"JSON array cannot be mapped to \" \\+ className","errorType":"exception","errorClass":"MappingException","httpStatus":null,"severity":"error","filePath":"json-path/src/main/java/com/jayway/jsonpath/spi/mapper/JakartaMappingProvider.java","lineNumber":310,"sourceCode":"     * @return instance of collection type identified by the argument\r\n     * @throws MappingException on a type that cannot be safely instantiated\r\n     */\r\n    private Collection<Object> newCollectionOfType(Class<?> collectionType) throws MappingException {\r\n        if (Collection.class.isAssignableFrom(collectionType)) {\r\n            if (!collectionType.isInterface()) {\r\n                @SuppressWarnings(\"unchecked\")\r\n                Collection<Object> coll = (Collection<Object>) newNoArgInstance(collectionType);\r\n                return coll;\r\n            } else if (List.class.isAssignableFrom(collectionType)) {\r\n                return new java.util.LinkedList<Object>();\r\n            } else if (Set.class.isAssignableFrom(collectionType)) {\r\n                return new java.util.LinkedHashSet<Object>();\r\n            } else if (Queue.class.isAssignableFrom(collectionType)) {\r\n                return new java.util.LinkedList<Object>();\r\n            }\r\n        }\r\n        String className = collectionType.getSimpleName();\r\n        throw new MappingException(\"JSON array cannot be mapped to \" + className);\r\n    }\r\n\r\n    /**\r\n     * Lists all publicly accessible constructors for the {@code Class}\r\n     * identified by the argument, including any constructors inherited\r\n     * from superclasses, and uses a no-args constructor, if available,\r\n     * to create a new instance of the class. If argument is interface, \r\n     * this method returns {@code null}.\r\n     * \r\n     * @param targetType class type to create instance of\r\n     * @return an instance of the class represented by the argument\r\n     * @throws MappingException if no-arg public constructor is not there \r\n     */\r\n    private Object newNoArgInstance(Class<?> targetType) throws MappingException {\r\n        if (targetType.isInterface()) {\r\n            return null;\r\n        } else {\r\n            for (Constructor<?> ctr : targetType.getConstructors()) {\r","sourceCodeStart":292,"sourceCodeEnd":328,"githubUrl":"https://github.com/json-path/JsonPath/blob/62a4c9f0f65ba3f625aa0867d64c528ba72d09ec/json-path/src/main/java/com/jayway/jsonpath/spi/mapper/JakartaMappingProvider.java#L292-L328","documentation":"When mapping a JSON array, newCollectionOfType() instantiates the requested Collection target type: concrete classes need a public no-arg constructor, and known interfaces (List, Set, Queue) are mapped to LinkedList/LinkedHashSet. If the target type is not a Collection subtype (e.g. Map or a POJO) or is an unrecognized Collection interface such as SortedSet or Deque, it throws MappingException because a JSON array cannot be materialized into that type.","triggerScenarios":"read(\"$.items\", SomeNonCollectionClass.class) where the path points to a JSON array and the class is not Collection-assignable, or requesting a Collection interface not handled by the if/else chain (e.g. SortedSet.class, Deque.class, Iterable.class), including via TypeRef/ParameterizedType whose raw type falls through.","commonSituations":"Typos in the target class; assuming all java.util Collection interfaces are supported (only List/Set/Queue branches exist, so SortedSet/Deque fail); trying to map an array directly into Map.class or a bean class; using a custom collection type without a no-arg constructor.","solutions":["Map the JSON array into a supported target: List.class, Set.class, Queue.class, or a concrete Collection class with a public no-arg constructor (e.g. ArrayList.class).","If you need Deque/SortedSet/etc., read into a supported interface first and convert: new java.util.TreeSet<>(jsonPath.read(path, List.class)).","Ensure the element type is conveyed via TypeRef, e.g. new TypeRef<List<Book>>(){}, so collection creation and element mapping both work.","If the target should be a single object rather than a collection, the JSON at that path must be an object, not an array — fix the path or the expected type."],"exampleFix":"// before\nList<Book> books = jsonPath.read(\"$.store.book\", SortedSet.class); // MappingException\n// after\nList<Book> books = jsonPath.read(\"$.store.book\", new TypeRef<List<Book>>() {});\nSortedSet<Book> sorted = new TreeSet<>(books);","handlingStrategy":"validation","validationCode":"static boolean mappableArrayTarget(Class<?> t) {\n    return java.util.Collection.class.isAssignableFrom(t)\n        && (!t.isInterface() || java.util.List.class.isAssignableFrom(t)\n            || java.util.Set.class.isAssignableFrom(t)\n            || java.util.Queue.class.isAssignableFrom(t));\n}","typeGuard":null,"tryCatchPattern":"try {\n    return jsonPath.read(path, targetType);\n} catch (MappingException e) {\n    return new ArrayList<>(jsonPath.read(path, List.class));\n}","preventionTips":["Only request List, Set, Queue, or concrete collection classes with public no-arg constructors as array targets.","Prefer TypeRef<List<T>> over custom collection types.","Check that the path actually points to a JSON array when a collection type is requested."],"tags":["json","type-mismatch","json-path","collection"],"backgroundTag":"type-mismatch","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"}