Skip to content
BrainRoad BrainRoad
Documentation Menu

Connection Problems

Troubleshoot WebSocket disconnects, channel drops, and dashboard connectivity.

On this page

WebSocket Disconnects

The dashboard and console use WebSocket connections to communicate with your agent in real time. If you see a “Disconnected” banner or the console stops updating, try these steps:

  1. Refresh the page. Most disconnects are transient. A refresh re-establishes the connection.
  2. Check your network. VPNs, corporate firewalls, and unstable Wi-Fi can interrupt WebSocket connections. Try switching networks or disabling your VPN temporarily.
  3. Check agent status. If the agent was stopped or restarted, the WebSocket connection drops. The dashboard will attempt to reconnect automatically, but you may need to refresh.

Channel Connection Dropped

WhatsApp, Signal, and other messaging channels maintain persistent sessions with your agent. These sessions can drop for several reasons:

  • Session expired. WhatsApp Web sessions expire after extended periods of inactivity. Re-scan the QR code from the agent’s channel settings to reconnect.
  • Agent restarted. Channel connections are re-established on boot, but some channels may require a fresh QR scan after a restart.
  • Phone disconnected. WhatsApp requires your phone to have an active internet connection. If your phone goes offline for too long, the session may be invalidated.

Check the Activity tab for channel-specific error messages that indicate what disconnected and why.

Console Not Connecting

If the Console tab shows a blank screen or a connection error, confirm your agent is running. The console requires an active agent to connect to. A stopped agent has no running container, so there is nothing for the console to attach to. Start the agent first, then open the console.

Browser Tab Is Blank

The agent’s browser viewer shows a live view of the agent’s browser instance. If it displays a blank or gray screen, the agent may not be actively browsing. The browser only renders content when the agent is performing a web-based task. This is normal — it does not indicate a problem unless you expected the agent to be browsing.