Envoy Gateway WebSocket Disconnects: Check the Idle Timeout

A WebSocket starts as ordinary HTTP. The connection has two phases:

1. HTTP handshake. The client sends GET /ws with Upgrade: websocket.
2. Upgraded stream. The Gateway returns 101 Switching Protocols. Frames then flow in both directions.

Which check you run depends on whether the handshake finished:

• No 101: look at routing, policy, and upgrade handling
• 101, then a later drop: look at stream lifetime and who closed the socket

Envoy Gateway already has a stream idle timeout when you do not attach a route-level BackendTrafficPolicy:

• The documented listener default is 5 minutes
• A BackendTrafficPolicy targeting the HTTPRoute can set a route-specific streamIdleTimeout instead of relying on the listener default
• A cloud load balancer, CDN, firewall, another proxy, or the backend can still close a WebSocket that Envoy would allow

Diagnose the disconnect first

Read the HTTP status before you change a timeout:

• HTTP 404 before the expected WebSocket upgrade: first check whether the hostname and path match the HTTPRoute. If the route matches, check whether the backend itself returned the 404
• HTTP 403: the request was rejected before a successful WebSocket upgrade. Check policies first, especially anything attached to this route
• HTTP 101: the WebSocket handshake succeeded
• HTTP 101, then a close frame (opcode 8): the application ended the socket
• HTTP 101, then an empty read or a reset and no close frame: check idle timers and the network path

                    WebSocket does not stay connected
                                    |
                                    v
                      Did the handshake return 101?
                                    |
                ┌───────────────────┴───────────────────┐
                NO                                     YES
                |                                       |
                404: check route/backend    Close frame (opcode 8)?
                403: check policies                     |
                                                        |
                                            ┌───────────┴───────────┐
                                           YES                      NO
                                            |                       |
                                       application         stream idle timeout,
                                          close             load balancer, or
                                                             the network path

A handshake you can recognize looks like this:

HTTP/1.1 101 Switching Protocols
Upgrade: websocket
Connection: Upgrade

101 means routing and the WebSocket upgrade worked. A timeout change does not fix a 404 or a 403.

Does Envoy Gateway need special WebSocket headers?

No. A normal HTTPRoute accepts the standard HTTP/1.1 upgrade. You do not add Connection or Upgrade with a header modifier. The client still has to send a valid WebSocket handshake, including Upgrade: websocket, Connection: Upgrade, Sec-WebSocket-Key, and Sec-WebSocket-Version.

This route is enough when the Gateway is already named eg and the backend Service is ws:

apiVersion: gateway.networking.k8s.io/v1
kind: HTTPRoute
metadata:
  name: ws
spec:
  parentRefs:
  - name: eg
  hostnames:
  - app.example.com
  rules:
  - matches:
    - path:
        type: PathPrefix
        value: /ws
    backendRefs:
    - name: ws
      port: 80

On Envoy Gateway v1.9.2 that route did this:

• It returned 101 and forwarded the backend's first frame
• With no route-level stream idle policy, a silent connection stayed open past 25 seconds
• That check is shorter than the documented 5 minute default, so it does not show the default firing

Configure the WebSocket idle timeout

streamIdleTimeout is how long a stream may sit with no upstream or downstream activity. The timeout does not measure how old the WebSocket connection is. A WebSocket can remain connected for hours as long as traffic keeps resetting the idle timer. Any frame in either direction resets the clock. This example uses 30 seconds so the reset is easy to picture. Use your own longest legitimate silence when you write the policy.

streamIdleTimeout is 30 seconds

     server sends a frame
               ↓
the timer returns to 30 seconds

the client sends a frame after 20 seconds
                    ↓
  the timer returns to 30 seconds again

no traffic for the full 30 seconds
                ↓
 Envoy treats the stream as idle

Two different idle fields show up in the API. Set the stream field for a WebSocket:

• streamIdleTimeout is no activity on an open stream. The listener default is 5 minutes.
• idleTimeout is a connection with no active request. The documented default is 1 hour. It is not this disconnect.

Attach the limit to the HTTPRoute with BackendTrafficPolicy:

• Omit streamIdleTimeout and the route keeps the listener value
• The 5 second setting below is only so a silent failure shows up quickly
• A real application usually wants a longer quiet period

apiVersion: gateway.envoyproxy.io/v1alpha1
kind: BackendTrafficPolicy
metadata:
  name: ws-idle
spec:
  targetRefs:
  - group: gateway.networking.k8s.io
    kind: HTTPRoute
    name: ws
  timeout:
    http:
      streamIdleTimeout: 5s

On v1.9.2 that 5 second policy closed the silent stream like this:

• The upstream stream ended after 5.001 seconds
• The client saw an empty read at 8.199 seconds, not a WebSocket close frame
• Close handling continued after the timer fired, so the YAML duration is not the exact time a browser will notice

Why heartbeats keep the connection alive

Any traffic on the stream can reset the idle timer:

• In this test the client sent a text message containing ping every 2 seconds
• That message is application data, not a WebSocket Ping control frame (opcode 9)
• Applications often send Ping and Pong control frames, or their own heartbeat messages
• Either kind of traffic counts as activity

The timer only cares that bytes or frames are flowing. It does not care whether that activity is business data or a heartbeat.

With the 5 second policy still in place, those text messages kept the connection open past 20 seconds. The interval has to be shorter than every idle timer on the path:

• the route streamIdleTimeout
• the listener default, when you did not set a route value
• a cloud load balancer, CDN, firewall, or other proxy in front of the Gateway

Raising only the Envoy value does not help when a shorter timer still sits in front of it.

How this differs from the HTTPRoute request timeout

HTTPRoute timeouts.request is the ordinary HTTP request deadline:

• Envoy Gateway's FAQ says that deadline can cut a long HTTP stream such as kubectl logs -f
• An upgraded WebSocket is a different case

The 15 second 504 is that ordinary deadline. For the WebSocket check, the same /ws rule was set to 5 seconds:

timeouts:
  request: 5s

On Envoy Gateway v1.9.2, once the HTTP/1.1 upgrade completed:

• timeouts.request: 5s did not close the upgraded WebSocket during a 15 second silent check
• The client still had 101 and the first frame, and the socket was still open at the end of that wait
• For WebSocket inactivity, configure streamIdleTimeout

Migrate WebSocket timeouts from ingress-nginx

ingress-nginx does not need a special upgrade annotation for WebSocket. Its docs tell you to raise both of these, and both default to 60 seconds:

• proxy-read-timeout: the allowed gap between reads from the upstream
• proxy-send-timeout: the allowed gap between writes to the upstream

Envoy's streamIdleTimeout is one clock for no activity in either direction. The proxy-read-timeout migration is the same distinction for ordinary HTTP.

Do not mechanically copy 60 to 60s. Pick streamIdleTimeout based on the longest period during which your WebSocket is legitimately expected to send no frames in either direction.

The same silent connection behaved differently under the two nginx settings:

• Defaults: the WebSocket stayed open through a 25 second sample
• Both annotations set to 5: the client got an empty read, and the backend saw the peer close at 5 seconds
• The symptom looked like the Envoy idle close. The fields are still not interchangeable.

Do not use requestBuffer on WebSocket routes

requestBuffer is incompatible with WebSocket upgrades on Envoy Gateway, so do not attach request buffering to the WebSocket route:

• Buffering waits for a complete request body
• A protocol upgrade turns the connection into a long-lived stream
• That field is the proxy-body-size replacement for a normal upload

This is the failing piece on the policy that targets the WebSocket HTTPRoute:

requestBuffer:
  limit: 1Ki

On Envoy Gateway v1.9.2, the same upgrade that had returned 101 then returned:

HTTP/1.1 403 Forbidden
connection: close
content-length: 0

The response had no application server header. Removing requestBuffer from that route brought the 101 back.

Backend close versus a proxy or network close

A WebSocket close frame uses opcode 8 and can carry a close code and a reason. When the test application closed the socket itself, the client received opcode 8 and the reason backend close.

An empty read or a TCP reset, with no opcode 8, means the connection ended without a WebSocket close frame. That does not prove Envoy did it. The cause can be:

• Envoy
• a load balancer
• a network failure
• a backend that died without writing a close frame

Compare the disconnect with streamIdleTimeout and with every other idle timer on the path before you change the application.

Troubleshooting

Summary

A WebSocket on Envoy Gateway is an HTTP handshake followed by a long-lived stream. HTTP 101 means the upgrade worked. A 404 means the expected upgrade did not happen, so check route matching and the backend. In the tested v1.9.2 setup, a 403 appeared when requestBuffer was attached to the WebSocket route. Neither result represents a WebSocket idle disconnect because the connection never reached the upgraded-stream stage.

With no route-specific policy, the documented stream idle default is 5 minutes, so a silent WebSocket may be closed after that idle period unless another device on the path closes it sooner. A BackendTrafficPolicy targeting the HTTPRoute can set a route-specific streamIdleTimeout instead of relying on that default. In the v1.9.2 check, 5 seconds closed the upstream stream at 5.001 seconds, and the client saw an empty read at 8.199 seconds. Text messages every 2 seconds reset the timer and kept the socket open past 20 seconds. Those messages were application data, not WebSocket Ping frames.

timeouts.request is a different clock. It can end an ordinary stream such as kubectl logs -f, but a 5 second request deadline did not close this upgraded WebSocket during a 15 second silent check. ingress-nginx proxy-read-timeout and proxy-send-timeout are directional quiet periods, not a field you copy onto streamIdleTimeout. When the application closes cleanly, look for opcode 8. An empty read only tells you the connection ended without that frame.

References

• Envoy Gateway v1.9 extension types
• Envoy Gateway FAQ
• Envoy timeout configuration
• ingress-nginx WebSocket guidance
• Gateway API HTTPRoute reference