quarkusio/quarkus · error · WebSocketClientException

Unable to obtain the connection from the Vert.x duplicated c

Error message

Unable to obtain the connection from the Vert.x duplicated context

What it means

Thrown by the WebSocket client connection supplier when it fails to retrieve the current WebSocket connection from the active Vert.x duplicated context. The connection is stored in a context local (WEB_SOCKET_CONN_LOCAL) which is only populated while executing on the duplicated context associated with an established client connection. If code runs on a plain context, a different context, or the connection local was never set, the lookup returns null and this error is thrown.

Source

Thrown at extensions/websockets-next/runtime/src/main/java/io/quarkus/websockets/next/runtime/WebSocketClientRecorder.java:28

import io.vertx.core.Context;
import io.vertx.core.Vertx;

@Recorder
public class WebSocketClientRecorder {

    public Supplier<Object> connectionSupplier() {
        return new Supplier<Object>() {

            @Override
            public Object get() {
                Context context = Vertx.currentContext();
                if (context != null && VertxContext.isDuplicatedContext(context)) {
                    Object connection = ContextSupport.WebSocketContextLocalsProvider.WEB_SOCKET_CONN_LOCAL.get(context);
                    if (connection != null) {
                        return connection;
                    }
                }
                throw new WebSocketClientException("Unable to obtain the connection from the Vert.x duplicated context");
            }
        };
    }

    public Supplier<Object> createContext(Map<String, ClientEndpoint> endpointMap) {
        return new Supplier<Object>() {
            @Override
            public Object get() {
                return new ClientEndpointsContext() {

                    @Override
                    public ClientEndpoint endpoint(String endpointClass) {
                        return endpointMap.get(endpointClass);
                    }

                };
            }
        };

View on GitHub (pinned to e1c734241f)

Solutions

Ensure the code runs on the Vert.x duplicated context captured for the connection (e.g. context.runOnContext or VertxContextSupport.executeBlocking-style helpers)
Do not manually switch thread/context inside endpoint callbacks; let websockets-next propagate the duplicated context
Verify the connection is actually established before invoking APIs that resolve the current connection
If you must hop threads, capture the duplicated context (Vertx.currentContext()) up front and restore it before the lookup

Example fix

// before
Executors.newSingleThreadExecutor().submit(() -> connection.send(...));
// after
context.runOnContext(v -> connection.send(...));

Defensive patterns

Strategy: try-catch

Validate before calling

io.vertx.core.Context ctx = Vertx.currentContext();
boolean ok = ctx != null && io.quarkus.websockets.next.runtime.VertxContext.isDuplicatedContext(ctx);

Type guard

static boolean hasConnectionInContext(io.vertx.core.Context ctx) {
    return ctx != null && io.quarkus.websockets.next.runtime.VertxContext.isDuplicatedContext(ctx);
}

Try / catch

try {
    connection.send(msg);
} catch (WebSocketClientException e) {
    // not on the connection's duplicated context; re-dispatch
    capturedContext.runOnContext(v -> connection.send(msg));
}

Prevention

Never spawn raw threads inside WebSocket endpoint callbacks
Use Quarkus context-aware executors for async work
Capture the duplicated context early and reuse it for delayed calls
Keep connection API calls within the endpoint lifecycle

When it happens

Trigger: Calling WebSocketConnection/endpoint APIs that resolve the current connection via the injected Supplier (connectionContext() style lookup) from outside the duplicated context of an active client connection — e.g. from a worker thread spawned manually, a scheduled task, a @PostConstruct, or before the connection is established.

Common situations: Delegating endpoint callbacks to a custom executor without capturing/switching back to the original duplicated context; calling connection lookup lazily after the endpoint lifecycle ended; using the client connection supplier from unrelated code paths.

Related errors

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