quarkusio/quarkus · error · UnsupportedOperationException

LocalEventBusCodec can only be used for local delivery

Error message

LocalEventBusCodec can only be used for local delivery

What it means

LocalEventBusCodec is a placeholder EventBus codec intended only for same-node (local) message delivery on the Vert.x event bus. Its encodeToWire/decodeFromWire methods throw UnsupportedOperationException because cluster-wide delivery would require real wire serialization, which this codec does not provide.

Source

Thrown at extensions/vertx/runtime/src/main/java/io/quarkus/vertx/LocalEventBusCodec.java:32

 */
public class LocalEventBusCodec<T> implements MessageCodec<T, T> {

    // We need a counter to generate unique name as the event bus does not support having 2 codecs with the same name
    // even if they are targeting different types.
    private static final AtomicInteger count = new AtomicInteger();
    private final String name;

    public LocalEventBusCodec() {
        this(LocalEventBusCodec.class.getName() + "-" + count.getAndIncrement());
    }

    public LocalEventBusCodec(String name) {
        this.name = name;
    }

    @Override
    public void encodeToWire(Buffer buffer, T t) {
        throw new UnsupportedOperationException("LocalEventBusCodec can only be used for local delivery");
    }

    @Override
    public T decodeFromWire(int pos, Buffer buffer) {
        throw new UnsupportedOperationException("LocalEventBusCodec can only be used for local delivery");
    }

    @Override
    public T transform(T instance) {
        return instance;
    }

    @Override
    public String name() {
        return name;
    }

    @Override

View on GitHub (pinned to e1c734241f)

Solutions

1. Remove clustering, or scope the message to local delivery (send/publish within one node / local delivery option)
2. Register a real clusterable codec (implement ClusterSerializable/serialize the payload type) and registerCodec via CodecRegistrar for the payload type
3. Use quarkus.vertx.cluster or EventBus codec configuration to register the cluster-safe codec for the message body type
4. Switch to Kafka/other transport if cross-node messaging with complex payloads is required

Example fix

// before
eventBus.registerCodec(new LocalEventBusCodec<>(MyPayload.class.getName()));
// message may traverse the cluster -> UnsupportedOperationException

// after
eventBus.registerCodec(new MyClusterablePayloadCodec()); // implements MessageCodec with real encodeToWire

boolean clustered = vertx.isClustered();
if (clustered && codec instanceof LocalEventBusCodec) {
    throw new IllegalStateException("Register a clusterable codec for " + bodyType + " in clustered mode");
}

try {
    eventBus.request(addr, payload, deliveryOptions);
} catch (UnsupportedOperationException e) {
    if (e.getMessage().contains("LocalEventBusCodec")) {
        registerClusterableCodec(); // then retry or fail with a clear message
    } else throw e;
}

When it happens

Trigger: Vert.x calls encodeToWire on the codec when a message using this codec must be serialized across a clustered event bus (delivery to another node) or when a clustered delivery attempt targets a consumer registered with a LocalEventBusCodec.

Common situations: Running the application in clustered mode (quarkus.vertx.cluster.enabled=true) while using a codec registered as local-only; sending a message to a remote consumer whose codec was registered via MessageCodec local codec conventions; the <T> type payload not being serializable so only a local codec was feasible.

Related errors

• Unknown JSON Value
• Invalid `codec` argument in @ConsumeEvent - no parameter
• An event consumer business method must accept exactly one pa
• An event consumer business method that accepts io.vertx.core
• Failed to encode as JSON:

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