When using the Mastodon web client, the error message “Streaming API Disconnected” appears in the browser console or as a visible notification. This error means the real-time connection between your browser and the Mastodon server has dropped. The streaming API is responsible for delivering new posts, notifications, and timeline updates without requiring a page refresh. A disconnection causes the timeline to stop updating in real time until the connection is re-established. This article explains the root cause of the disconnection and provides step-by-step fixes to restore the streaming API connection.
Key Takeaways: Restore Real-Time Timeline Updates
- Browser developer console (F12) > Network tab: Identify if WebSocket connections are failing or being closed by the server.
- Mastodon instance status page: Check if the streaming server is online and accepting connections.
- Browser extension settings: Disable ad blockers or VPN extensions that may block WebSocket traffic to the instance domain.
Why the Streaming API Disconnects on the Mastodon Web Client
The Mastodon web client communicates with the server using two main channels: HTTP requests for actions like posting and loading pages, and WebSocket connections for the streaming API. The streaming API uses WebSockets to push new data to the browser in real time. When the WebSocket connection is interrupted, the client displays “Streaming API Disconnected.” This can happen for several reasons.
Server-Side Timeouts and Resource Limits
Most Mastodon instances set a timeout on idle WebSocket connections. If no data is sent for a period, typically 30 to 60 seconds, the server closes the connection to free resources. Some instances also limit the number of simultaneous WebSocket connections per user. If you have multiple tabs open, each one creates a separate WebSocket, which may exceed the limit.
Network Interruptions and Proxy Interference
WebSocket connections require a persistent TCP connection. Any network interruption, such as a Wi-Fi drop, VPN reconnection, or proxy server timeout, will break the WebSocket. Browser extensions that block or modify traffic, particularly ad blockers, VPN extensions, and script blockers, may interfere with the WebSocket handshake or keep-alive packets.
Browser-Specific Issues
Some browsers, especially older versions, have bugs in their WebSocket implementation. Aggressive power-saving modes on laptops can also suspend JavaScript execution, causing the WebSocket to time out. The Mastodon web client relies on JavaScript to maintain the WebSocket connection; if the browser suspends the tab, the connection drops.
Steps to Fix the Streaming API Disconnected Error
Follow these steps in order. Test after each step to see if the error resolves.
- Refresh the Mastodon tab
Press Ctrl+R or F5 on Windows, or Cmd+R on Mac. This forces the browser to re-establish the WebSocket connection. If the error was temporary, this may resolve it immediately. - Close other Mastodon tabs
Each open Mastodon tab creates a separate WebSocket connection. Close all but one tab. Wait 10 seconds and check if the error disappears. - Disable browser extensions temporarily
Open the browser extension manager. Disable all extensions, especially ad blockers, privacy tools, and VPN extensions. Restart the browser and open Mastodon again. If the error stops, re-enable extensions one by one to find the culprit. - Check the Mastodon instance status
Visit the status page for your instance. Many instances have a status subdomain like status.mastodon.social. Look for the streaming server status. If it shows offline or degraded, wait until the administrator resolves the issue. - Clear browser cache and cookies for the instance domain
Go to browser settings > Privacy and security > Clear browsing data. Select “Cookies and other site data” and “Cached images and files.” Set the time range to “Last 24 hours.” Clear the data, then reload Mastodon. - Use a different browser
Test Mastodon in a browser you do not normally use, such as Firefox if you use Chrome, or Edge if you use Firefox. If the error does not appear, the original browser may have a WebSocket bug or extension conflict. - Disable VPN or proxy temporarily
Turn off any VPN service or system proxy. WebSocket connections often fail through VPNs due to port restrictions or traffic shaping. After disabling, refresh the Mastodon tab. - Adjust browser power-saving settings
On Windows 11 or Windows 10, go to Settings > System > Power & battery. Set the power mode to “Best performance.” In the browser, disable any option that suspends background tabs. For Chrome, go to chrome://settings/performance and turn off “Memory Saver” and “Energy Saver.” - Use the Mastodon mobile app or a third-party client
If the web client continues to disconnect, try the official Mastodon mobile app or a desktop client like Tusky or Elk. These clients handle WebSocket reconnection more robustly.
If the Streaming API Still Disconnects After the Main Fix
Error persists on multiple devices on the same network
If the error occurs on different devices connected to the same Wi-Fi or LAN, the problem is likely network-level. Check if your router is blocking WebSocket traffic. Some corporate or school networks block WebSocket ports 80 and 443. Contact your network administrator. Alternatively, use a mobile hotspot to test.
Error occurs only on one specific instance
If you can connect to other Mastodon instances without issues, the problem is specific to the instance you are using. The instance may be overloaded or have misconfigured WebSocket settings. Report the issue to the instance administrator. Include the exact error message and the time it occurred.
WebSocket connection shows 101 Switching Protocols but then closes
Open the browser developer console with F12. Go to the Network tab and filter by “WS” or “WebSocket.” Reload the page. Look for the WebSocket connection to your instance domain. If the status shows 101 but the connection closes after a few seconds, the server is actively terminating the connection. This could be due to rate limiting or an authentication token expiration. Log out of Mastodon, clear cookies, and log in again.
Manual WebSocket Reconnection vs Automatic Reconnection
| Item | Manual Reconnection | Automatic Reconnection |
|---|---|---|
| Trigger | User refreshes the page or closes and reopens the tab | Browser or client attempts to reconnect after a delay |
| Time to restore | Immediate after refresh | Typically 5 to 30 seconds depending on client logic |
| Reliability | High, but requires user action | Varies by client implementation; may fail if underlying issue persists |
| Network overhead | Full page reload, higher data usage | Only WebSocket handshake, lower data usage |
| Best for | Occasional disconnections | Frequent disconnections due to network instability |
The Mastodon web client attempts automatic reconnection after a disconnection, but this may fail if the root cause is not addressed. If you see the error repeatedly, do not rely on automatic reconnection alone. Apply the fixes above to eliminate the cause.
After following these steps, the streaming API connection should remain stable. Refresh the Mastodon tab and verify that new posts appear in the home timeline without manual reload. If the error continues on one browser but not another, consider switching to the browser that works. For persistent issues on all browsers, check the instance status page and report the problem to the administrator.