quarkusio/quarkus · error · WebSocketServerException

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 server-side WebSocket connection supplier when it cannot read the WebSocket connection from the Vert.x duplicated context local (WEB_SOCKET_CONN_LOCAL). The connection is only registered on the duplicated context bound to a live server connection; any other context yields null and this WebSocketServerException.

Source

Thrown at extensions/websockets-next/runtime/src/main/java/io/quarkus/websockets/next/runtime/WebSocketServerRecorder.java:84

    private final RuntimeValue<WebSocketsServerRuntimeConfig> runtimeConfig;

    public WebSocketServerRecorder(final RuntimeValue<WebSocketsServerRuntimeConfig> runtimeConfig) {
        this.runtimeConfig = runtimeConfig;
    }

    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 WebSocketServerException("Unable to obtain the connection from the Vert.x duplicated context");
            }
        };
    }

    public Handler<RoutingContext> createEndpointHandler(String generatedEndpointClass, String endpointId,
            boolean activateRequestContext, boolean activateSessionContext, String endpointPath) {
        ArcContainer container = Arc.container();
        ConnectionManager connectionManager = container.instance(ConnectionManager.class).get();
        Codecs codecs = container.instance(Codecs.class).get();
        HttpUpgradeCheck[] httpUpgradeChecks = getHttpUpgradeChecks(endpointId, container);
        TrafficLogger trafficLogger = TrafficLogger.forServer(runtimeConfig.getValue());
        WebSocketTelemetryProvider telemetryProvider = container.instance(WebSocketTelemetryProvider.class).orElse(null);
        return new Handler<RoutingContext>() {

            @Override
            public void handle(RoutingContext ctx) {
                if (ctx.request().headers().contains(HandshakeRequest.SEC_WEBSOCKET_KEY)) {
                    UserData userData = new UserDataImpl();

View on GitHub (pinned to e1c734241f)

Solutions

Run the code on the duplicated context of the connection (capture it and use context.runOnContext)
Avoid manual thread switching inside WebSocket endpoint callbacks; use Quarkus context-aware executors
Ensure the endpoint method executes while the connection is still open
If using @Blocking or scheduled work, re-attach the captured duplicated context before the call

Example fix

// before
CompletableFuture.runAsync(() -> connection.sendBlocking(msg));
// after
capturedContext.runOnContext(v -> connection.sendBlocking(msg));

Defensive patterns

Strategy: try-catch

Validate before calling

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

Type guard

static boolean isServerConnection(Object c) {
    return c instanceof io.quarkus.websockets.next.runtime.WebSocketConnectionImpl;
}

Try / catch

try {
    connection.send(msg);
} catch (WebSocketServerException e) {
    capturedDuplicatedContext.runOnContext(v -> connection.send(msg));
}

Prevention

Run all connection work on the endpoint's duplicated context
Avoid manual thread pools in server endpoints; use Quarkus context propagation
Don't cache the connection Supplier for use after the connection closes
Prefer QuarkusSecureExecutorService / context-aware executors

When it happens

Trigger: Invoking WebSocketConnection APIs (via the injected Supplier) outside the endpoint's duplicated context — e.g. from a manually created thread, an executor, a timer, or after the connection closed and locals were cleared.

Common situations: Bridging to a separate thread pool without context propagation; calling connection-related code in application startup; storing the Supplier and calling it later from another request context.

Related errors

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