json-path/JsonPath · error · IllegalArgumentException

TypeRef not supported: " + typeName

Error message

TypeRef not supported: " + typeName

What it means

In getRawClass(), any Type that is neither Class, ParameterizedType, nor GenericArrayType — e.g. a wildcard type (?), a type variable (T), or a TypeVariable embedded in a TypeRef — is unsupported. The provider throws IllegalArgumentException("TypeRef not supported: <typeName>") because it cannot determine the concrete raw class to databind into.

Source

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

                    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 wildcard or type-variable generics with concrete classes in the TypeRef: new TypeRef<List<Book>>(){}, not new TypeRef<List<?>>(){}.
2. In generic helper methods, pass the concrete Class/TypeRef from the call site rather than the erased T.
3. Read into List<Map<String,Object>> and convert manually if the element type is dynamic.
4. Catch IllegalArgumentException and provide a fallback target type.

Example fix

// before
List<?> items = jsonPath.read("$.items", new TypeRef<List<?>>() {}); // IllegalArgumentException: TypeRef not supported
// after
List<Map<String, Object>> items = jsonPath.read("$.items", new TypeRef<List<Map<String, Object>>>() {});

static boolean isConcreteType(java.lang.reflect.Type t) {
    return t instanceof Class
        || (t instanceof ParameterizedType
            && java.util.Arrays.stream(((ParameterizedType) t).getActualTypeArguments())
                .allMatch(a -> a instanceof Class || a instanceof ParameterizedType));
}

boolean usableTypeRef(java.lang.reflect.Type t) {
    return !(t instanceof javax.lang.model.type.WildcardType)
        && !(t instanceof java.lang.reflect.TypeVariable);
}

try {
    return jsonPath.read(path, typeRef);
} catch (IllegalArgumentException e) {
    return jsonPath.read(path, new TypeRef<List<Map<String, Object>>>() {});
}

When it happens

Trigger: Passing a TypeRef or Type whose underlying type is a wildcard (List<?>) or an unresolved type variable (T) — e.g. new TypeRef<List<?>>(){} or generic helper methods that forward T — into read(path, typeRef) on JakartaMappingProvider.

Common situations: Generic wrapper methods like <T> T read(String path) forwarding T to TypeRef; using wildcard generics in TypeRef declarations; erasure surprises where the resolved TypeVariable instead of a Class reaches the mapper.

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

• Cannot map JSON element to " + typeName
• No type info in TypeRef
• InvalidJsonException
• InvalidJsonException
• an array or object instance is expected

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