WebSocket Client Connection Evicted/Shutdown During Handshake in Vert.x 5.0.5

[yogurt-c]

Version

5.0.5

Context

🐛 Bug Report: Intermittent WebSocket Client Connection Eviction/Shutdown During Handshake

🎯 Version

• Vert.x Version: 5.0.5
• Operating System: macOS (Apple Silicon - M1)
• Java: 21

Java Version: OpenJDK 21

📝 Description

I'm encountering an issue where the **WebSocket client connection is being unexpectedly shut down (ShutdownEvent / Connection evicted) immediately after sending the WebSocket handshake request, and before receiving the server's handshake response. This issue occurs intermittently (occasionally), not on every attempt, but when it does, it prevents the WebSocket connection from being established. The client is connecting to a locally developed Vert.x WebSocket server.

✅ Expected Behavior

The WebSocket client should wait for the server's handshake response. If the response is valid, the connection should be upgraded to a WebSocket connection and stay active. The connection should not be shut down or evicted during the handshake phase unless explicitly requested or due to a network error/timeout.

❌ Actual Behavior

Intermittently, the connection is closed/evicted during the handshake phase, specifically after the handshake request is sent and before a response is received.

The log shows a USER_EVENT: io.vertx.core.net.impl.ShutdownEvent which leads to a Connection evicted warning and subsequent connection closure, as shown below:

... (Handshake Request WRITE/FLUSH occurs before this)
2025-12-05 16:25:21 DEBUG [vert.x-eventloop-thread-2] i.n.handler.logging.LoggingHandler - [id: 0xe82a509f, L:/127.0.0.1:55615 - R:localhost/127.0.0.1:47136] ACTIVE
2025-12-05 16:25:21 DEBUG [vert.x-eventloop-thread-2] i.n.handler.logging.LoggingHandler - [id: 0xbe1d97b4, L:/127.0.0.1:55615 - R:localhost/127.0.0.1:47136] USER_EVENT: io.vertx.core.net.impl.ShutdownEvent@4909845e
2025-12-05 16:25:21 WARN  [vert.x-eventloop-thread-2] i.v.c.h.i.HttpClientConnectionInternal - Connection evicted
2025-12-05 16:25:21 DEBUG [vert.x-eventloop-thread-2] i.n.handler.logging.LoggingHandler - [id: 0xbe1d97b4, L:/127.0.0.1:55615 - R:localhost/127.0.0.1:47136] WRITE: 0B
2025-12-05 16:25:21 DEBUG [vert.x-eventloop-thread-2] i.n.handler.logging.LoggingHandler - [id: 0xbe1d97b4, L:/127.0.0.1:55615 - R:localhost/127.0.0.1:47136] FLUSH
2025-12-05 16:25:21 DEBUG [vert.x-eventloop-thread-2] i.n.handler.logging.LoggingHandler - [id: 0xbe1d97b4, L:/127.0.0.1:55615 - R:localhost/127.0.0.1:47136] CLOSE
2025-12-05 16:25:21 DEBUG [vert.x-eventloop-thread-2] i.n.handler.logging.LoggingHandler - [id: 0xbe1d97b4, L:/127.0.0.1:55615 ! R:localhost/127.0.0.1:47136] INACTIVE

Steps to reproduce

1. Create Http Server with webSocketHandshakeHandler, webSocketHandler
2. Use the WebSocketClient to initiate a WebSocket connection.
3. The client sends the WebSocket handshake GET request.
4. Immediately following the write/flush of the handshake request, a ShutdownEvent is processed on the connection, leading to an eviction.

Do you have a reproducer?

No response

[HarshMehta112]

After review, I identified an intermittent issue with WebSocket handshakes. The failures occurred because the underlying HTTP connection remained in the connection pool during the upgrade process and could be evicted by lifecycle checks. If eviction happened mid-handshake, the WebSocket upgrade would fail.

To address this, the connection is explicitly evicted from the pool immediately before initiating the WebSocket upgrade. This prevents lifecycle shutdowns during the handshake and stabilizes WebSocket establishment.

add line at

vert.x/vertx-core/src/main/java/io/vertx/core/http/impl/http1x/Http1xClientConnection.java

Line 1022 in 7ee44a0

try {

// Evict connection from pool before starting WebSocket handshake
evictionHandler.handle(null);

This change aligns the behavior of toWebSocket() with toNetSocket() and results in more reliable WebSocket connections.

@vietj If this approach aligns with the project’s direction, I’m happy to refine or extend the solution as needed. As I’m still new to contributing, any feedback would be greatly appreciated.

[vietj]

we should try to a get a reproducer for this case, I think it is possible, the idea would be to evict the connection from the pool when the handshake is in progress. Then probably that when we request a WebSocket upgrade we should evict the connection from the pool since it will not be pooled anymore