Skip to content

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

  1. Open the browser devtools Network tab, filter by ws. A single ws or wss connection should establish with HTTP 101 and stay open
  2. If the server is HTTPS, the socket must be wss too. Mixed content will be blocked by the browser
  3. On the proxy, confirm HTTP/1.1 to upstream and upgrade headers are passed
  4. Increase idle timeouts so long tasks do not drop the socket
  5. 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.