Resolving Mattermost WebSocket Failures and 502 Bad Gateway in Reverse Proxies

Mattermost users often encounter a persistent 'Connecting...' status in the desktop client or intermittent message delivery, even when the web interface appears to load partially. This discrepancy usually indicates a failure in the reverse proxy (such as Nginx or HAProxy) to properly handle WebSocket connections. Because Mattermost relies on WebSockets for real-time updates, a standard HTTP configuration is insufficient for production environments.

To resolve this, you must ensure your proxy is explicitly configured to allow connection upgrades and possesses sufficient timeout limits to prevent premature termination of idle sockets.

Diagnostic Identification

Before changing configurations, identify whether the failure is occurring at the network layer or the application layer using the table below:

SymptomLikely CausePrimary Diagnostic Check Persistent 'Connecting...' status in clientProxy failing to upgrade to WebSocketCheck Browser Network Tab for WS traffic)'502 Bad Gateway' on refreshProxy cannot reach Mattermost serviceCheck Mattermost service status and port bindingMessages only appear after manual page refreshAggressive proxy timeout settingsCheck proxy error logs for 'timeout timed out'Images/assets broken in mobile appSiteURL mismatchCheck config.json 'SiteURL' value

Step-by-Step Diagnostics

Follow these checks in order to isolate the point of failure.

1. Verify the WebSocket Handshake

Open Mattermost in a Chrome-based browser, open the Developer Tools (F12), and navigate to the Network tab. Filter by WS (WebSockets). Refresh the page.

• If you see a 101 Switching Protocols status, the WebSocket is functional.
• If you see 400, 502, or constant closing, the proxy is rejecting the upgrade request.

2. Inspect Server-Side Logs

Check the Mattermost server logs (typically located at var/log/mattermost/mattermost.log) for specific error strings. Use the following command:

tail -f /var/log/mattermost/mattermost.log

Look for: websocket write error or connection reset by peer. If these errors appear exactly when a client attempts to connect, the proxy is likely closing the connection prematurely.

3. Validate API Reachability

Ensure the proxy is at least routing standard API traffic correctly. Use curl from a remote machine:

curl -I https://your-mattermost-url.com/api/v4/users/

Verify the response returns a 200 OK. If it returns a 502, the issue is between the proxy and the Mattermost container/service.

Configuration Fixes

Fixing Nginx Proxy

If you use Nginx, your location block for Mattermost must include specific headers to support WebSockets. Update your configuration file (usually in /etc/nginx/sites-available/):

location / {
    proxy_pass http://localhost:8065;
    proxy_set_header Host $host;
    proxy_set_header X-Real-IP $remote_addr;
    proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
    proxy_set_header X-Forwarded-Proto $scheme;

    # Required for WebSockets
    proxy_set_header Upgrade $http_upgrade;
    proxy_set_header Connection "upgrade";
    
    # Prevent premature timeouts
    proxy_read_timeout 300s;
    proxy_send_timeout 300s;
    proxy_connect_timeout 60s;
}

Note: After editing, run sudo systemctl reload nginx to apply changes.

Aligning the SiteURL

Mattermost uses the SiteURL setting to generate internal links and handle CORS. If this does not match your public URL exactly, mobile apps and assets will fail.

Open /opt/mattermost/config/config.json and verify entry:

"SiteURL": "https://mattermost.example.com",

Restart the Mattermost service after changing this value: sudo systemctl restart mattermost.

Verification and Escalation

Once fixes are applied, verify the result by:

• Checking the Browser Network tab again; the WS connection should now show a 101 status and remain 'Open'.
• Sending a message from the mobile app and ensuring it appears instantly on the desktop client without a refresh.

Escalation: If the issue persists, check if there is an intermediate Load Balancer (like AWS ALB or Cloudflare) between the user and your proxy. These services have their own idle timeout settings that may override Nginx configurations.