json-path/JsonPath · error · MappingException

Cannot map JSON element to " + typeName

Error message

Cannot map JSON element to " + typeName

What it means

getRawClass() reduces a java.lang.reflect Type to its raw Class for databinding. Class and ParameterizedType (e.g. List<Book>) are handled, but a GenericArrayType — a type like T[] or Book[] obtained through generics/TypeRef — has no single raw class the mapper can target, so it throws MappingException "Cannot map JSON element to <typeName>". The provider does not support generic array databinding.

Source

Thrown at json-path/src/main/java/com/jayway/jsonpath/spi/mapper/JakartaMappingProvider.java:377

                if (Modifier.isPublic(mods) && !Modifier.isAbstract(mods) &&
                        name.equals(method.getName()) &&
                        Arrays.equals(paramTypes, method.getParameterTypes())) {
                    return method;
                }
            }
            clazz = clazz.getSuperclass();
        }
        return null;
    }

    private Class<?> getRawClass(Type targetType) {
        if (targetType instanceof Class) {
            return (Class<?>) targetType;
        } else if (targetType instanceof ParameterizedType) {
            return (Class<?>) ((ParameterizedType) targetType).getRawType();
        } else if (targetType instanceof GenericArrayType) {
            String typeName = targetType.getTypeName();
            throw new MappingException("Cannot map JSON element to " + typeName);
        } else {
            String typeName = targetType.getTypeName();
            throw new IllegalArgumentException("TypeRef not supported: " + typeName);
        }
    }

    private Type getFirstTypeArgument(Type targetType) {
        if (targetType instanceof ParameterizedType) {
            Type[] args = ((ParameterizedType) targetType).getActualTypeArguments();
            if (args != null && args.length > 0) {
                if (args[0] instanceof Class) {
                    return (Class<?>) args[0];
                } else if (args[0] instanceof ParameterizedType) {
                    return (ParameterizedType) args[0];
                }
            }
        }
        return null;

View on GitHub (pinned to 62a4c9f0f6)

Solutions

1. Replace array target types with collections: new TypeRef<List<Book>>(){} instead of new TypeRef<Book[]>(){}.
2. If the array type is a plain concrete class (e.g. int[].class is a Class), verify what Type you actually pass — only GenericArrayType triggers this; restructure generics so a concrete Class is resolved.
3. Read as List<Object> and convert with list.toArray(new Book[0]) manually.
4. Catch MappingException and fall back to the List-based mapping.

Example fix

// before
List<Book> books = java.util.Arrays.asList(jsonPath.read("$.store.book", new TypeRef<Book[]>() {})); // MappingException
// after
List<Book> books = jsonPath.read("$.store.book", new TypeRef<List<Book>>() {});

static boolean isArrayType(java.lang.reflect.Type t) {
    return t instanceof GenericArrayType
        || (t instanceof Class && ((Class<?>) t).isArray());
}

boolean safeTarget(java.lang.reflect.Type t) {
    return t instanceof Class || t instanceof ParameterizedType;
}

try {
    return jsonPath.read(path, typeRef);
} catch (MappingException e) {
    return jsonPath.read(path, new TypeRef<List<T>>() {});
}

When it happens

Trigger: read(path, new TypeRef<Book[]>(){}) or any TypeRef/field generic resolving to an array type (G[]), where G is itself generic, so the Type is a GenericArrayTypeImpl rather than a plain Class.

Common situations: Using TypeRef with array syntax instead of List; mapping generic methods whose return Type is T[]; migrating code from Jackson-backed providers (which support arrays) to the Jakarta/JSON-P provider which does not.

Understand the failure class

Background: UnsupportedOperationException and "is not supported" errors: when a library deliberately refuses a call — this error's family across 30 libraries.

Related errors

• JSON array cannot be mapped to " + className
• TypeRef not supported: " + typeName
• Cannot create JSON iterator for " + value
• Can only rename properties in a map
• Can only add to an array

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