quarkusio/quarkus · error · IllegalStateException

@ConsumeEvent annotation must target a method

Error message

@ConsumeEvent annotation must target a method

What it means

During build, EventBusCodecProcessor scans @ConsumeEvent annotations to register custom codecs and expects each annotation to be on a method (the event consumer). If an instance targets something else (e.g. a class or field), the build fails with this IllegalStateException.

Source

Thrown at extensions/vertx/deployment/src/main/java/io/quarkus/vertx/deployment/EventBusCodecProcessor.java:64

    private static final DotName LOCAL_EVENT_BUT_CODEC = DotName.createSimple(LocalEventBusCodec.class);

    @BuildStep
    public void registerCodecs(
            BeanArchiveIndexBuildItem beanArchiveIndexBuildItem,
            CombinedIndexBuildItem combinedIndex,
            BuildProducer<MessageCodecBuildItem> messageCodecs,
            BuildProducer<ReflectiveClassBuildItem> reflectiveClass,
            BuildProducer<LocalCodecSelectorTypesBuildItem> localCodecSelectorTypes) {

        final IndexView index = beanArchiveIndexBuildItem.getIndex();
        Collection<AnnotationInstance> consumeEventAnnotationInstances = index.getAnnotations(CONSUME_EVENT);
        Map<DotName, DotName> codecByTypes = new HashMap<>();
        Set<DotName> selectorTypes = new HashSet<>();

        for (AnnotationInstance consumeEventAnnotationInstance : consumeEventAnnotationInstances) {
            AnnotationTarget typeTarget = consumeEventAnnotationInstance.target();
            if (typeTarget.kind() != AnnotationTarget.Kind.METHOD) {
                throw new IllegalStateException("@ConsumeEvent annotation must target a method");
            }
            MethodInfo method = typeTarget.asMethod();

            Type codecTargetFromParameter = extractPayloadTypeFromParameter(method);
            // If the @ConsumeEvent set the codec, use this codec. It applies to the parameter
            AnnotationValue codec = consumeEventAnnotationInstance.value("codec");
            if (codec != null && codec.asClass().kind() == Type.Kind.CLASS) {
                if (codecTargetFromParameter == null) {
                    throw new IllegalStateException("Invalid `codec` argument in @ConsumeEvent - no parameter");
                }
                codecByTypes.put(codecTargetFromParameter.name(), codec.asClass().asClassType().name());
            } else if (codecTargetFromParameter != null && !hasBuiltInCodec(codecTargetFromParameter)) {
                // Codec is not set and built-in codecs cannot be used
                if (!codecByTypes.containsKey(codecTargetFromParameter.name())) {
                    if (isConcreteClass(codecTargetFromParameter, index)) {
                        // The default codec makes only sense for concrete classes
                        LOGGER.debugf("Local Message Codec registered for type %s",
                                codecTargetFromParameter);

View on GitHub (pinned to e1c734241f)

Solutions

1. Move @ConsumeEvent onto a public method that takes the event payload parameter
2. Remove the annotation from the class/field
3. If you intended class-level subscription, implement an observer bean method instead

Example fix

// before
@ConsumeEvent
@ApplicationScoped
public class MyConsumer { }
// after
@ApplicationScoped
public class MyConsumer {
    @ConsumeEvent("my-address")
    public void consume(String msg) { }
}

// check placement before build
for (var f : MyConsumer.class.getDeclaredMethods()) {
    if (f.isAnnotationPresent(ConsumeEvent.class) && f.getParameterCount() == 0)
        throw new IllegalStateException("@ConsumeEvent must be on a method with a payload parameter");
}

When it happens

Trigger: Putting @ConsumeEvent on a class, field, or constructor instead of a business method; annotation-placement mistakes or copy/paste from other messaging annotations.

Common situations: Developer annotates a bean class thinking it registers a consumer; IDE auto-import places the annotation on the wrong element; migration from another framework's annotation semantics.

Related errors

• Invalid `codec` argument in @ConsumeEvent - no parameter
• An event consumer business method with two parameters must h
• An event consumer business method with two parameters must n
• Unimplemented mode of use of 'io.quarkus.runtime.logging.Log
• Unknown type

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