quarkusio/quarkus · error · IllegalStateException

An event consumer business method must accept exactly one pa

Error message

An event consumer business method must accept exactly one parameter: %s [method: %s, bean:%s]

What it means

During Quarkus deployment, the Vert.x extension validates every @ConsumeEvent business method on CDI beans. A consumer method must take exactly one parameter (payload, Message, or Message+MultiMap headers as a special two-parameter case); anything else is rejected at build time so the failure surfaces before the application runs.

Source

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

                    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));
                    }
                    if (method.hasAnnotation(RunOnVirtualThread.class) && consumeEvent.value("ordered") != null
                            && consumeEvent.value("ordered").asBoolean()) {
                        throw new IllegalStateException(String.format(
                                "An event consumer business method that cannot use @RunOnVirtualThread and set the ordered attribute to true [method: %s, bean:%s]",
                                method, bean));
                    }

                    InvokerBuilder builder = invokerFactory.createInvoker(bean, method)
                            .withInstanceLookup();

View on GitHub (pinned to e1c734241f)

Solutions

Change the method to accept exactly one parameter (the event payload, or io.vertx.core.eventbus.Message / io.vertx.mutiny.core.eventbus.Message)
If you need delivery headers, use exactly two parameters with io.vertx.core.MultiMap as the first and the payload as the second
Remove stray parameters; inject other dependencies via fields/constructor instead of method parameters
If the payload type is wrong, declare the expected payload type and Quarkus decodes the message body for you

Example fix

// before
@ConsumeEvent("greeting")
void consume(String payload, String locale) { ... }

// after
@ConsumeEvent("greeting")
void consume(Greeting greeting) { ... } // or two params: (MultiMap headers, String payload)

Defensive patterns

Strategy: validation

Validate before calling

int count = method.getParameterCount();
boolean suspend = isKotlinSuspend(method);
if (suspend) count--;
if (!(count == 1 || (count == 2 && method.getParameterTypes()[0] == MultiMap.class))) {
    throw new IllegalStateException("@ConsumeEvent method must take 1 param (or 2 with MultiMap headers first): " + method);
}

Prevention

Always give @ConsumeEvent methods exactly one payload parameter
Use (MultiMap headers, T payload) when you need headers — exactly two params
Inject collaborators via fields/constructor, not consumer method parameters
Rebuild early: the error is a build-time failure, so any compile+build cycle catches it

When it happens

Trigger: Declaring a method annotated @ConsumeEvent with zero parameters, three or more parameters, or two parameters whose first is not MultiMap (the two-parameter check throws a sibling error, and 0/3+ params hit this one after parametersCount adjustments for Kotlin suspend methods).

Common situations: Refactoring a consumer signature and forgetting the event payload; copying a Spring @EventListener-style method into Quarkus; adding a second helper parameter like a principal or injected config; Kotlin suspend fun miscount because the continuation is subtracted.

Related errors

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