quarkusio/quarkus · error · IllegalStateException

Unable to instantiate InvokerReceiver:

Error message

Unable to instantiate InvokerReceiver:

What it means

ReceiverManager eagerly instantiates every class named in the configured invoker-receiver class list at startup by loading it through the thread-context class loader and calling its no-arg constructor. If any class is missing, not a Receiver, lacks a no-arg constructor, or its constructor throws, the manager aborts with this IllegalStateException naming the failing class.

Source

Thrown at extensions/signals/runtime/src/main/java/io/quarkus/signals/runtime/impl/ReceiverManager.java:71

    ReceiverManager(SignalsContext signalsContext,
            ReceiverExecutor executor,
            @All List<SignalMetadataEnricher> allEnrichers,
            @All List<ReceiverInterceptor> allInterceptors,
            BeanContainer beanContainer) {
        this.executor = executor;
        this.beanContainer = beanContainer;
        this.enrichers = orderByIdentifier(allEnrichers, signalsContext.orderedEnricherIds());
        this.interceptors = orderByIdentifier(allInterceptors, signalsContext.orderedInterceptorIds());
        this.resolvedReceivers = new ConcurrentHashMap<>();
        this.receivers = new ConcurrentHashMap<>();
        List<String> invokerReceiversClasses = signalsContext.receiversClasses();
        ClassLoader tccl = Thread.currentThread().getContextClassLoader();
        for (String irc : invokerReceiversClasses) {
            try {
                Receiver<?, ?> r = (Receiver<?, ?>) tccl.loadClass(irc).getConstructor().newInstance();
                receivers.put(irc, wrapReceiver(r));
            } catch (Exception e) {
                throw new IllegalStateException("Unable to instantiate InvokerReceiver:" + irc);
            }
        }
    }

    @Override
    public <T> Signal<T> create(Class<T> type, Annotation... qualifiers) {
        return new SignalImpl<T>(type, Set.of(qualifiers), Map.of(), this);
    }

    @Override
    public <T> Signal<T> create(TypeLiteral<T> type, Annotation... qualifiers) {
        return new SignalImpl<T>(type.getType(), Set.of(qualifiers), Map.of(), this);
    }

    List<SignalMetadataEnricher> enrichers() {
        return enrichers;
    }

View on GitHub (pinned to e1c734241f)

Solutions

  1. Fix the class name in the invoker-receivers configuration so it matches the fully-qualified class on the runtime classpath
  2. Give the receiver class a public no-arg constructor (or fix any exception thrown in that constructor)
  3. Verify the class implements io.quarkus.signals Receiver and is public non-abstract
  4. Check the class is in the application archive/dependencies so the TCCL can load it

Example fix

// before
class MyReceiver implements Receiver<Object, Object> {
    public MyReceiver(String cfg) { ... }
}
// after
class MyReceiver implements Receiver<Object, Object> {
    public MyReceiver() { ... }
}
Defensive patterns

Strategy: validation

Validate before calling

Class<?> c = Thread.currentThread().getContextClassLoader().loadClass(fqcn);
Receiver<?, ?> r = (Receiver<?, ?>) c.getDeclaredConstructor().newInstance(); // must be public, no-arg

Type guard

boolean isInstantiableReceiver(Class<?> c) {
    return Receiver.class.isAssignableFrom(c)
        && !c.isInterface() && !java.lang.reflect.Modifier.isAbstract(c.getModifiers())
        && Arrays.stream(c.getConstructors()).anyMatch(k -> k.getParameterCount() == 0);
}

Try / catch

try { receivers.put(fqcn, wrap((Receiver<?, ?>) tccl.loadClass(fqcn).getConstructor().newInstance())); }
catch (ReflectiveOperationException | ClassCastException e) {
    throw new IllegalStateException("Receiver not instantiable: " + fqcn, e);
}

Prevention

When it happens

Trigger: A class listed in invokerReceiversClasses cannot be loaded (typo, wrong package, not on TCCL) or cannot be instantiated (abstract, no public no-arg constructor, constructor throws).

Common situations: Typo or stale class name in quarkus.signals receiver configuration; custom Receiver written without a public no-arg constructor; receiver class moved/renamed after upgrade; class present only in a module not visible to the runtime TCCL.

Related errors

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