mirror of
https://github.com/browseros-ai/BrowserOS.git
synced 2026-05-18 19:16:22 +00:00
c79c775fb8
Images in docs/images/ are served as broken 130-byte placeholders by Mintlify CDN. Co-locating images with the MDX file (matching the working pattern in features/workflow/ and features/cowork/) bypasses this issue. Also fixes the Slack link placeholder. Co-authored-by: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
107 lines
3.7 KiB
Plaintext
107 lines
3.7 KiB
Plaintext
---
|
|
title: "Has Agent Crashed?"
|
|
description: "How to fix connection issues when the BrowserOS agent is not responding"
|
|
---
|
|
|
|
If you see **"Failed to Fetch"** or **"Unable to connect to BrowserOS agent"**, your agent has been killed.
|
|
|
|
<Frame>
|
|
<img src="/troubleshooting/failed-to-fetch-error.png" alt="Failed to fetch error" />
|
|
</Frame>
|
|
|
|
## Windows: Did you allow the BrowserOS Agent?
|
|
|
|
When BrowserOS starts for the first time on Windows, a popup will ask if you want to allow **BrowserOS Agent** to access the network. Click **Allow** — the agent runs as a separate process alongside the browser and needs this permission to work. If you clicked **Cancel** or missed this prompt, the agent won't be able to connect.
|
|
|
|
<Frame>
|
|
<img src="/troubleshooting/windows-installation-allow-browseros-agent.png" alt="Allow BrowserOS Agent network access prompt" />
|
|
</Frame>
|
|
|
|
To fix this, go to **Windows Security → Allow an app through your network settings**, and make sure **BrowserOS Agent** is enabled.
|
|
|
|
## Fix It
|
|
|
|
<Steps>
|
|
<Step title="Go to Settings → MCP Server and click Restart">
|
|
Open **Settings** from the sidebar, scroll to the MCP Server section, and click **Restart**. Wait a couple of minutes.
|
|
|
|
<Frame>
|
|
<img src="/troubleshooting/mcp-server-restart.png" alt="Click Restart in MCP Server Settings" />
|
|
</Frame>
|
|
</Step>
|
|
|
|
<Step title="If restart doesn't work, restart the BrowserOS Agent manually">
|
|
<Tabs>
|
|
<Tab title="Windows">
|
|
1. Open **Task Manager** — press `Ctrl + Shift + Esc` or right-click the taskbar and select **Task Manager**.
|
|
2. In the search bar at the top, type **browseros agent**.
|
|
3. Right-click **BrowserOS Agent** and select **End task**.
|
|
4. Reopen **BrowserOS** — the agent will restart automatically.
|
|
|
|
<Frame>
|
|
<img src="/troubleshooting/troubleshoot-search-restart-agent-task-manager.png" alt="Search for BrowserOS Agent in Task Manager and restart it" />
|
|
</Frame>
|
|
|
|
<Note>If the agent still doesn't reconnect, end both **BrowserOS** and **BrowserOS Agent** in Task Manager, then reopen the app.</Note>
|
|
</Tab>
|
|
<Tab title="macOS">
|
|
Right-click BrowserOS in the Dock → **Quit**, then reopen the app.
|
|
</Tab>
|
|
</Tabs>
|
|
</Step>
|
|
</Steps>
|
|
|
|
## Still Not Working?
|
|
|
|
<AccordionGroup>
|
|
<Accordion title="Check if another application is using the port">
|
|
The agent runs on port `9100` by default. If another application is using this port, BrowserOS cannot start the agent.
|
|
|
|
<Tabs>
|
|
<Tab title="macOS/Linux">
|
|
Find the process:
|
|
```bash
|
|
lsof -i :9100
|
|
```
|
|
|
|
Kill it (replace `PID` with the process ID from above):
|
|
```bash
|
|
kill -9 PID
|
|
```
|
|
</Tab>
|
|
<Tab title="Windows">
|
|
Find the process:
|
|
```powershell
|
|
netstat -ano | findstr :9100
|
|
```
|
|
|
|
Kill it (replace `PID` with the process ID from above):
|
|
```powershell
|
|
taskkill /PID PID /F
|
|
```
|
|
</Tab>
|
|
</Tabs>
|
|
|
|
Then restart BrowserOS.
|
|
</Accordion>
|
|
|
|
<Accordion title="Check your firewall or antivirus settings">
|
|
Some firewalls may block local connections. Make sure your firewall allows connections to `127.0.0.1:9100`.
|
|
|
|
**Windows users:** Antivirus software sometimes triggers a false positive. Try temporarily disabling your antivirus and restarting BrowserOS.
|
|
</Accordion>
|
|
</AccordionGroup>
|
|
|
|
## Get Help
|
|
|
|
If you're still experiencing issues, reach out:
|
|
|
|
<CardGroup cols={2}>
|
|
<Card title="Discord" icon="discord" href="https://discord.gg/YKwjt5vuKr">
|
|
Get help from the community
|
|
</Card>
|
|
<Card title="Slack" icon="slack" href="https://dub.sh/browserOS-slack">
|
|
Join our Slack
|
|
</Card>
|
|
</CardGroup>
|