WebSockets

Table of contents

• Requirements for WebSockets
• Quick checklist

WebSockets are critical for CloudBeaver. 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: CloudBeaver 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 CloudBeaver, 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.