quarkusio/quarkus · error · IllegalArgumentException

Raw Map parameter types are not supported. Offending method

Error message

Raw Map parameter types are not supported. Offending method is: {jandexMethod}

What it means

The REST client reactive build-time processor rejects JAX-RS client interface methods whose parameter (or return) type is a raw `Map` (declared as `Map` instead of `Map<K,V>`). It needs the key and value types at build time to generate the serialization/deserialization bytecode. A raw type leaves those types unknown, so deployment fails with this IllegalArgumentException.

Source

Thrown at extensions/resteasy-reactive/rest-client-jaxrs/deployment/src/main/java/io/quarkus/jaxrs/client/reactive/deployment/JaxrsClientReactiveProcessor.java:3397

                componentType = type.name().toString();
                paramArray = notNullParam.invokeStaticMethod(
                        MethodDescriptor.ofMethod(ToObjectArray.class, "value", Object[].class, Object.class),
                        paramHandle);
            }

            addWebTargetParamToWebTarget(notNullParam, notNullParam.load(paramName), webTarget, client, genericType,
                    paramAnnotations, paramArray, componentType, result, webTargetParamMethod, separator);
        }

        isParamNull.trueBranch().assign(result, webTarget);

        return result;
    }

    private Map.Entry<Type, Type> resolveMapTypes(Type type, MethodInfo jandexMethod) {
        if (type.name().equals(ResteasyReactiveDotNames.MAP)) {
            if (type.kind() != PARAMETERIZED_TYPE) {
                throw new IllegalArgumentException(
                        "Raw Map parameter types are not supported. Offending method is: " + jandexMethod);
            }
            var parameterizedType = type.asParameterizedType();
            var arguments = parameterizedType.arguments();
            return new AbstractMap.SimpleEntry<>(arguments.get(0), arguments.get(1));
        } else if (type.name().equals(ResteasyReactiveDotNames.MULTI_VALUED_MAP)) {
            if (type.kind() != PARAMETERIZED_TYPE) {
                throw new IllegalArgumentException(
                        "Raw MultivaluedMap parameter types are not supported. Offending method is: " + jandexMethod);
            }
            var parameterizedType = type.asParameterizedType();
            var arguments = parameterizedType.arguments();
            return new AbstractMap.SimpleEntry<>(arguments.get(0), ParameterizedType.create(ResteasyReactiveDotNames.LIST,
                    new Type[] { arguments.get(1) }, null));
        }
        // TODO: we could support this if necessary by looking up the resolved types via JandexUtil.resolveTypeParameters
        throw new IllegalArgumentException("Unsupported Map type '" + type.name() + "'. Offending method is: " + jandexMethod);
    }

View on GitHub (pinned to e1c734241f)

Solutions

Parameterize the Map, e.g. declare `Map<String, String>` or `Map<String, List<String>>` instead of raw `Map`
If the map represents form data, use `jakarta.ws.rs.core.MultivaluedMap<String, String>` with explicit type arguments
If a generic JSON object body is intended, use `Map<String, Object>` or a String/JsonNode instead of a raw Map

Example fix

// before
@POST Response send(@HeaderParam("h") Map headers);
// after
@POST Response send(@HeaderParam("h") Map<String, String> headers);

Defensive patterns

Strategy: validation

Validate before calling

if (!methodParamType.getClass().getComponentTypeOrRaw().equals(Object.class) && methodParamType instanceof Map) { /* ensure generics: */ Type t = field.getGenericType(); if (t instanceof ParameterizedType pt) { assert pt.getActualTypeArguments().length == 2; } }

Type guard

static boolean isParameterizedMap(java.lang.reflect.Type t) { return t instanceof ParameterizedType pt && Map.class.isAssignableFrom((Class<?>) pt.getRawType()); }

Prevention

Always use generic types in REST client interface method signatures
Enable compiler lint -Xlint:rawtypes to catch raw types at compile time
Review client interfaces with an arch unit test that scans for raw Map params

When it happens

Trigger: Declaring a resource method parameter like `@HeaderParam("h") Map headers` or `@FormParam`/`@BeanParam` containing a raw Map in a REST client interface; the Quarkus REST client processor hits it while generating the client stub at build time.

Common situations: Migrating a server-side resource interface to a client interface where raw Maps compiled fine with Classic RESTEasy; generic Map used to 'simplify' method signatures; code written before generics were applied.

Related errors

AI-assisted analysis of quarkusio/quarkus@e1c734241f (2026-09-05). Data as JSON: /api/errors/65e96c7422d9ec0b. Report an issue: GitHub.