> ## Documentation Index
> Fetch the complete documentation index at: https://docs.fased.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Browser Troubleshooting

# Browser Troubleshooting (Linux)

## Problem: "Failed to start Chrome CDP on port 18800"

Fased's browser control server fails to launch Chrome/Brave/Edge/Chromium with the error:

```
{"error":"Error: Failed to start Chrome CDP on port 18800 for profile \"fased\"."}
```

### Root Cause

On Ubuntu and many Linux distros, the default Chromium installation is a
**snap package**. Snap's AppArmor confinement interferes with how Fased spawns
and monitors the browser process.

The `apt install chromium` command installs a stub package that redirects to snap:

```
Note, selecting 'chromium-browser' instead of 'chromium'
chromium-browser is already the newest version (2:1snap1-0ubuntu2).
```

This is NOT a real browser — it's just a wrapper.

### Solution 1: Install Google Chrome (Recommended)

Install the official Google Chrome `.deb` package, which is not sandboxed by snap:

```bash theme={"theme":{"light":"min-light","dark":"min-dark"}}
wget https://dl.google.com/linux/direct/google-chrome-stable_current_amd64.deb
sudo dpkg -i google-chrome-stable_current_amd64.deb
sudo apt --fix-broken install -y  # if there are dependency errors
```

Then update your Fased config (`~/.fased/fased.json`):

```json theme={"theme":{"light":"min-light","dark":"min-dark"}}
{
  "browser": {
    "enabled": true,
    "executablePath": "/usr/bin/google-chrome-stable",
    "headless": true,
    "noSandbox": true
  }
}
```

### Solution 2: Use Snap Chromium with Attach-Only Mode

If you must use snap Chromium, configure Fased to attach to a manually-started browser:

1. Update config:

```json theme={"theme":{"light":"min-light","dark":"min-dark"}}
{
  "browser": {
    "enabled": true,
    "attachOnly": true,
    "headless": true,
    "noSandbox": true
  }
}
```

2. Start Chromium manually:

```bash theme={"theme":{"light":"min-light","dark":"min-dark"}}
chromium-browser --headless --no-sandbox --disable-gpu \
  --remote-debugging-port=18800 \
  --user-data-dir=$HOME/.fased/browser/fased/user-data \
  about:blank &
```

3. Optionally create a systemd user service to auto-start Chrome:

```ini theme={"theme":{"light":"min-light","dark":"min-dark"}}
# ~/.config/systemd/user/fased-browser.service
[Unit]
Description=Fased Browser (Chrome CDP)
After=network.target

[Service]
ExecStart=/snap/bin/chromium --headless --no-sandbox --disable-gpu \
  --remote-debugging-port=18800 \
  --user-data-dir=%h/.fased/browser/fased/user-data \
  about:blank
Restart=on-failure
RestartSec=5

[Install]
WantedBy=default.target
```

Enable with: `systemctl --user enable --now fased-browser.service`

### Verifying the Browser Works

Check status:

```bash theme={"theme":{"light":"min-light","dark":"min-dark"}}
curl -s http://127.0.0.1:18791/ | jq '{running, pid, chosenBrowser}'
```

Test browsing:

```bash theme={"theme":{"light":"min-light","dark":"min-dark"}}
curl -s -X POST http://127.0.0.1:18791/start
curl -s http://127.0.0.1:18791/tabs
```

### Config Reference

* `browser.enabled`: enable browser control. Default: `true`.
* `browser.executablePath`: path to a Chromium-based browser binary, such as
  Chrome, Brave, Edge, or Chromium. Default: auto-detected.
* `browser.headless`: run without GUI. Default: `false`.
* `browser.noSandbox`: add `--no-sandbox` for Linux setups that need it.
  Default: `false`.
* `browser.attachOnly`: attach to an existing browser instead of launching one.
  Default: `false`.
* `browser.cdpPort`: Chrome DevTools Protocol port. Default: `18800`.

### Problem: "Chrome extension relay is running, but no tab is connected"

You’re using the `chrome` profile (extension relay). It expects the Fased
browser extension to be attached to a live tab.

Fix options:

1. **Use the managed browser:** `fased browser start --browser-profile fased`
   (or set `browser.defaultProfile: "fased"`).
2. **Use the extension relay:** install the extension, open a tab, and click the
   browser relay extension icon to attach it.

Notes:

* The `chrome` profile uses your **system default Chromium browser** when possible.
* Local `fased` profiles auto-assign `cdpPort`/`cdpUrl`; only set those for remote CDP.