http2

docs/troubleshooting/connection-error.mdx

@@ -77,7 +77,10 @@ WebSocket support is required for Open WebUI v0.5.0 and later. If WebSockets are
 1. **Check your reverse proxy configuration** - Ensure `Upgrade` and `Connection` headers are properly set
 2. **Verify CORS settings** - WebSocket connections respect CORS policies
 3. **Check browser console** - Look for WebSocket connection errors
-4. **Test direct connection** - Try connecting directly to Open WebUI without the proxy to isolate the issue
+4. **Test direct connection** - Try connecting directly to Open WebUI without the proxy to isolate the issue.
+5. **Check for HTTP/2 WebSocket Issues** - Some proxies (like HAProxy 3.x) enable HTTP/2 by default. If your proxy handles client connections via HTTP/2 but the backend/application doesn't support RFC 8441 (WebSockets over H2) properly, the instance may "freeze" or stop responding. 
+   - **Fix for HAProxy**: Add `option h2-workaround-bogus-websocket-clients` to your configuration or force the backend connection to use HTTP/1.1.
+   - **Fix for Nginx**: Ensure you are using `proxy_http_version 1.1;` in your location block (which is the default in many Open WebUI examples).
 
 For multi-instance deployments, configure Redis for WebSocket management:
 ```bash

docs/tutorials/https/haproxy.md

@@ -117,6 +117,20 @@ backend owui_chat
     http-request add-header X-CLIENT-IP %[src]
  http-request set-header X-Forwarded-Proto https if { ssl_fc }
     server chat <ip>:3000
+
+## WebSocket and HTTP/2 Compatibility
+
+Starting with recent versions (including HAProxy 3.x), HAProxy may enable HTTP/2 by default. While HTTP/2 supports WebSockets (RFC 8441), some clients or backend configurations may experience "freezes" or unresponsiveness when icons or data start loading via WebSockets over an H2 tunnel.
+
+If you experience these issues:
+1. **Force HTTP/1.1 for WebSockets**: Add `option h2-workaround-bogus-websocket-clients` to your `frontend` or `defaults` section. This prevents HAProxy from advertising RFC 8441 support to the client, forcing a fallback to the more stable HTTP/1.1 Upgrade mechanism.
+2. **Backend Version**: Ensure your backend connection is using HTTP/1.1 (the default for `mode http`).
+
+Example addition to your `defaults` or `frontend`:
+```shell
+defaults
+    # ... other settings
+    option h2-workaround-bogus-websocket-clients
 ```
 
 You will see that we have ACL records (routers) for both Open WebUI and Let's Encrypt. To use WebSocket with OWUI, you need to have an SSL configured, and the easiest way to do that is to use Let's Encrypt.

docs/tutorials/https/nginx.md

@@ -25,6 +25,17 @@ A very common and difficult-to-debug issue with WebSocket connections is a misco
 
 Failure to do so will cause WebSocket connections to fail, even if you have enabled "Websockets support" in Nginx Proxy Manager.
 
+### HTTP/2 and WebSockets
+
+If you enable **HTTP/2** on your Nginx server, ensure that your proxy configuration still uses **HTTP/1.1** for the connection to the Open WebUI backend. This is crucial as most WebUI features (like streaming and real-time updates) rely on WebSockets, which are more stable when handled via HTTP/1.1 `Upgrade` than over the newer RFC 8441 (WebSockets over H2) in many proxy environments.
+
+In your Nginx location block, always include:
+```nginx
+proxy_http_version 1.1;
+proxy_set_header Upgrade $http_upgrade;
+proxy_set_header Connection "upgrade";
+```
+
 :::
 
 Choose the method that best fits your deployment needs.