quarkusio/quarkus · error · IllegalStateException

An event consumer business method with two parameters must h

Error message

An event consumer business method with two parameters must have MultiMap as the first parameter: %s [method: %s, bean:%s]

What it means

VertxProcessor validates event consumer methods at build time. A @ConsumeEvent method with two parameters must declare MultiMap (headers) as its first parameter and a payload or Message as the second. If the first parameter is not MultiMap, the build fails with this IllegalStateException naming parameters, method, and bean.

Source

Thrown at extensions/vertx/deployment/src/main/java/io/quarkus/vertx/deployment/VertxProcessor.java:175

        AnnotationStore annotationStore = beanRegistrationPhase.getContext().get(BuildExtension.Key.ANNOTATION_STORE);
        for (BeanInfo bean : beanRegistrationPhase.getContext().beans().classBeans()) {
            for (MethodInfo method : bean.getTarget().get().asClass().methods()) {
                if (method.isSynthetic()) {
                    continue;
                }
                AnnotationInstance consumeEvent = annotationStore.getAnnotation(method, CONSUME_EVENT);
                if (consumeEvent != null) {
                    // Validate method params and return type
                    int parametersCount = method.parametersCount();
                    if (KotlinUtils.isKotlinSuspendMethod(method)) {
                        parametersCount--;
                    }

                    List<Type> params = method.parameterTypes();
                    if (parametersCount == 2) {
                        if (!isMessageHeaders(params.get(0).name())) {
                            // If there are two parameters, the first must be message headers.
                            throw new IllegalStateException(String.format(
                                    "An event consumer business method with two parameters must have MultiMap as the first parameter: %s [method: %s, bean:%s]",
                                    params, method, bean));
                        } else if (isMessage(params.get(1).name())) {
                            throw new IllegalStateException(String.format(
                                    "An event consumer business method with two parameters must not accept io.vertx.core.eventbus.Message or io.vertx.mutiny.core.eventbus.Message: %s [method: %s, bean:%s]",
                                    params, method, bean));
                        }
                    } else if (parametersCount != 1) {
                        throw new IllegalStateException(String.format(
                                "An event consumer business method must accept exactly one parameter: %s [method: %s, bean:%s]",
                                params, method, bean));
                    }
                    if (method.returnType().kind() != Kind.VOID && VertxConstants.isMessage(params.get(0).name())
                            && !KotlinUtils.isKotlinSuspendMethod(method)) {
                        throw new IllegalStateException(String.format(
                                "An event consumer business method that accepts io.vertx.core.eventbus.Message or io.vertx.mutiny.core.eventbus.Message must return void [method: %s, bean:%s]",
                                method, bean));
                    }

View on GitHub (pinned to e1c734241f)

Solutions

Put MultiMap first: method(MultiMap headers, T payload) or method(MultiMap headers, Message<T> msg)
Reduce to a single parameter if headers are not needed
Use a single Message<T> parameter and read msg.headers() instead

Example fix

// before
@ConsumeEvent("addr")
public void on(Message<String> msg, String extra) { }
// after
@ConsumeEvent("addr")
public void on(MultiMap headers, Message<String> msg) { }

Defensive patterns

Strategy: validation

Validate before calling

// enforce (MultiMap, X) ordering for two-param consumers
for (Method m : MyConsumer.class.getDeclaredMethods()) {
    if (m.isAnnotationPresent(ConsumeEvent.class) && m.getParameterCount() == 2
        && !MultiMap.class.isAssignableFrom(m.getParameterTypes()[0])) {
        throw new IllegalStateException("First parameter must be MultiMap: " + m);
    }
}

Prevention

Remember the convention: MultiMap first, payload second
Prefer single-parameter (payload or Message<T>) consumers when headers aren't needed
Add an ArchUnit/test rule for consumer signatures

When it happens

Trigger: Declaring a two-parameter consumer whose first parameter is anything other than io.vertx.core.MultiMap / io.vertx.mutiny.core.MultiMap (e.g. Message first, or custom type first).

Common situations: Developer tries (Message, payload) ordering; confusion with other frameworks' (headers, body) conventions; signature drift after refactoring.

Related errors

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