{"record":{"id":"fcbf8ab726d99494","repo":"quarkusio/quarkus","slug":"localeventbuscodec-can-only-be-used-for-local-deli","errorCode":null,"errorMessage":"LocalEventBusCodec can only be used for local delivery","messagePattern":"LocalEventBusCodec can only be used for local delivery","errorType":"exception","errorClass":"UnsupportedOperationException","httpStatus":null,"severity":"error","filePath":"extensions/vertx/runtime/src/main/java/io/quarkus/vertx/LocalEventBusCodec.java","lineNumber":32,"sourceCode":" */\npublic class LocalEventBusCodec<T> implements MessageCodec<T, T> {\n\n    // We need a counter to generate unique name as the event bus does not support having 2 codecs with the same name\n    // even if they are targeting different types.\n    private static final AtomicInteger count = new AtomicInteger();\n    private final String name;\n\n    public LocalEventBusCodec() {\n        this(LocalEventBusCodec.class.getName() + \"-\" + count.getAndIncrement());\n    }\n\n    public LocalEventBusCodec(String name) {\n        this.name = name;\n    }\n\n    @Override\n    public void encodeToWire(Buffer buffer, T t) {\n        throw new UnsupportedOperationException(\"LocalEventBusCodec can only be used for local delivery\");\n    }\n\n    @Override\n    public T decodeFromWire(int pos, Buffer buffer) {\n        throw new UnsupportedOperationException(\"LocalEventBusCodec can only be used for local delivery\");\n    }\n\n    @Override\n    public T transform(T instance) {\n        return instance;\n    }\n\n    @Override\n    public String name() {\n        return name;\n    }\n\n    @Override","sourceCodeStart":14,"sourceCodeEnd":50,"githubUrl":"https://github.com/quarkusio/quarkus/blob/e1c734241f34c7919086ceb4c9262b4a58f6de44/extensions/vertx/runtime/src/main/java/io/quarkus/vertx/LocalEventBusCodec.java#L14-L50","documentation":"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.","triggerScenarios":"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.","commonSituations":"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.","solutions":["Remove clustering, or scope the message to local delivery (send/publish within one node / local delivery option)","Register a real clusterable codec (implement ClusterSerializable/serialize the payload type) and registerCodec via CodecRegistrar for the payload type","Use quarkus.vertx.cluster or EventBus codec configuration to register the cluster-safe codec for the message body type","Switch to Kafka/other transport if cross-node messaging with complex payloads is required"],"exampleFix":"// before\neventBus.registerCodec(new LocalEventBusCodec<>(MyPayload.class.getName()));\n// message may traverse the cluster -> UnsupportedOperationException\n\n// after\neventBus.registerCodec(new MyClusterablePayloadCodec()); // implements MessageCodec with real encodeToWire\n","handlingStrategy":"fallback","validationCode":"boolean clustered = vertx.isClustered();\nif (clustered && codec instanceof LocalEventBusCodec) {\n    throw new IllegalStateException(\"Register a clusterable codec for \" + bodyType + \" in clustered mode\");\n}","typeGuard":null,"tryCatchPattern":"try {\n    eventBus.request(addr, payload, deliveryOptions);\n} catch (UnsupportedOperationException e) {\n    if (e.getMessage().contains(\"LocalEventBusCodec\")) {\n        registerClusterableCodec(); // then retry or fail with a clear message\n    } else throw e;\n}","preventionTips":["Use clusterable codecs whenever quarkus.vertx.cluster.enabled=true","Register codecs for payload types via CodecRegistrar at startup","Restrict LocalEventBusCodec usage to single-node deployments","Prefer built-in serialization (ClusterSerializable) for cross-node payloads"],"tags":["vertx","eventbus","codec","clustering","serialization"],"backgroundTag":"codec-cannot-serialize","analyzedSha":"e1c734241f34c7919086ceb4c9262b4a58f6de44","analyzedAt":"2026-09-05T17:01:29.979Z","contentChangedAt":"2026-09-05T17:01:29.979Z","schemaVersion":2},"datasetVersion":"2026-09-12T22:17:10.623Z"}