WebSockets
WebSockets are critical for Team Edition. If they are blocked, the UI may look normal but never refresh, SSO may hang, and query results may not appear.
Typical traffic over the socket includes:
- the SSO login flow
- metadata changes (scripts, connections)
- SQL execution
Requirements for WebSockets¶
Important
Team Edition deployments are preconfigured. The socket uses the same host and
port, and switches to wss
when the server uses HTTPS. For details on enabling HTTPS in Team Edition,
see Force HTTPS mode.
If you use a different proxy or network stack, make sure it meets these requirements. No extra ports or domains are needed:
Area | Requirement |
---|---|
Protocol | Use HTTP/1.1 to upstream, do not downgrade to HTTP/1.0 |
Upgrade | Pass Upgrade and Connection: upgrade headers unchanged |
Connection stability | Keep the socket open with generous read/idle timeouts |
Scheme | Match the server scheme: ws:// over HTTP, wss:// over HTTPS |
Endpoint | /api/ws on the same host and port (e.g. wss://<your-domain>/api/ws ) |
TCP port | Same as the server - no extra port required |
Metadata | Preserve Host , X-Forwarded-Proto , and related headers |
Proxy behavior | Do not rewrite, buffer, or compress WebSocket frames |
Load balancing | Pin a client to the same backend for the socket’s lifetime |
Network filtering | Ensure firewalls, VPNs, and security proxies allow WebSocket traffic |
CDN/WAF | Some providers (e.g., Cloudflare) block WebSockets by default – enable them |
Quick checklist¶
- Open the browser devtools Network tab, filter by
ws
. A singlews
orwss
connection should establish with HTTP 101 and stay open - If the server is HTTPS, the socket must be
wss
too. Mixed content will be blocked by the browser - On the proxy, confirm HTTP/1.1 to upstream and upgrade headers are passed
- Increase idle timeouts so long tasks do not drop the socket
- Check corporate VPNs or filtering proxies that block or rewrite WebSockets
Tip
If the socket connects, then closes after a minute or two, it is usually a proxy or load balancer timeout. Increase the read timeout, and keep HTTP/1.1 with upgrade headers.