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

# Troubleshooting

> Solutions for common FERAL issues — installation errors, connection problems, and runtime failures.

## Diagnostic Tool

Before diving into specific issues, run the built-in diagnostic:

```bash theme={null}
feral doctor
```

This checks Python/Node versions, dependencies, port availability, LLM connectivity, BLE adapters, and more. Fix any items marked with `✗` first.

## Common Issues

### `command not found: feral`

The `feral` binary is not on your PATH.

<Tabs>
  <Tab title="One-liner install">
    The installer creates a virtual environment at `~/.feral-env`. Activate it:

    ```bash theme={null}
    source ~/.feral-env/bin/activate
    ```

    To make this permanent, add the line to your shell profile:

    <CodeGroup>
      ```bash ~/.zshrc theme={null}
      echo 'source ~/.feral-env/bin/activate' >> ~/.zshrc
      ```

      ```bash ~/.bashrc theme={null}
      echo 'source ~/.feral-env/bin/activate' >> ~/.bashrc
      ```
    </CodeGroup>
  </Tab>

  <Tab title="Git clone install">
    Ensure `feral-core` is installed in your active Python environment:

    ```bash theme={null}
    cd FERAL-AI/feral-core
    pip install -e ".[llm]"
    which feral
    ```
  </Tab>

  <Tab title="Docker">
    The `feral` CLI is not available on the host with Docker installs. Use `docker compose exec` instead:

    ```bash theme={null}
    docker compose exec brain feral status
    ```
  </Tab>
</Tabs>

### No LLM Key Configured

```
Error: No LLM provider configured. Run 'feral setup' to set one up.
```

Run the setup wizard to choose a provider and enter your API key:

```bash theme={null}
feral setup
```

For quick configuration without the wizard:

<CodeGroup>
  ```bash Anthropic theme={null}
  export ANTHROPIC_API_KEY=sk-ant-...
  ```

  ```bash OpenAI theme={null}
  export OPENAI_API_KEY=sk-...
  ```

  ```bash Ollama (local, no key needed) theme={null}
  # Just ensure Ollama is running:
  ollama serve
  ```
</CodeGroup>

<Tip>
  Ollama is auto-detected on `localhost:11434` and requires no API key. It's the fastest way to get running.
</Tip>

### Port 9090 Already in Use

```
Error: Port 9090 is already in use. (exit code 4)
```

Another process is occupying the brain's default port.

```bash theme={null}
# Find what's using the port
lsof -i :9090

# Option 1: Kill the process
kill -9 <PID>

# Option 2: Use a different port
feral start --port 9091
```

### WebSocket Connection Refused

The dashboard or a client can't connect to the brain.

**Checklist:**

1. Is the brain running? → `feral status`
2. Correct port? → Default is `9090`, check `--port` flag or `FERAL_BRAIN_PORT`
3. Firewall blocking? → Allow `localhost:9090` in your firewall
4. Docker networking? → Use `host.docker.internal` instead of `localhost` from containers

```bash theme={null}
# Quick connectivity test
curl http://localhost:9090/api/dashboard/status
```

### Pair URL works on Mac but not on phone (LAN)

**Symptom:** QR scans to `http://<lan-ip>:9090/pair?...` but phone shows connection failed.

Most common fixes:

1. Ensure FERAL is bound on all interfaces:

```bash theme={null}
FERAL_HOST=0.0.0.0 feral start
```

2. Regenerate the pairing link in `Devices` -> `Pair new device`.
3. Confirm phone and Mac are on the same network and WiFi does not block client-to-client traffic (AP isolation).

### Anywhere mode selected but pairing still fails

**Symptom:** Pairing returns remote-mode errors (no public URL / Mode C unavailable).

Run:

```bash theme={null}
feral access remote-up
feral access status
```

If needed, complete Tailscale login first:

```bash theme={null}
tailscale up
```

To revert:

```bash theme={null}
feral access remote-down
```

### Playwright Chromium Missing

```
Error: Browser not found. Run 'playwright install chromium'.
```

The computer-use features (browser automation, screen capture) depend on Playwright. Install the browser:

```bash theme={null}
playwright install chromium
```

<Note>
  If you don't need computer-use features, you can skip the Playwright install — the brain boots cleanly without it; the affected skills will report `Browser unavailable` until Playwright is present. Earlier docs claimed a `FERAL_COMPUTER_USE` env flag, but that variable was never wired into the code. The supported way to keep computer-use cold is to set autonomy mode to `strict` from the WebUI **Settings → Autonomy** picker — every action then needs explicit approval before it runs.
</Note>

### pip Install Failures

**Symptom:** Dependency resolution errors or build failures during install.

<Steps>
  <Step title="Upgrade pip">
    ```bash theme={null}
    pip install --upgrade pip setuptools wheel
    ```
  </Step>

  <Step title="Use the LLM extras">
    ```bash theme={null}
    pip install -e ".[llm]"
    ```
  </Step>

  <Step title="Install system dependencies (Linux)">
    Some packages need system libraries:

    ```bash theme={null}
    sudo apt install build-essential libffi-dev libssl-dev portaudio19-dev
    ```
  </Step>

  <Step title="Try a fresh virtual environment">
    ```bash theme={null}
    python3.11 -m venv ~/.feral-env-fresh
    source ~/.feral-env-fresh/bin/activate
    pip install -e ".[llm]"
    ```
  </Step>
</Steps>

### BLE Adapter Not Found

```
Warning: No BLE adapter detected. Hardware scanning disabled.
```

* **macOS:** BLE is built-in. Grant Bluetooth permission to your terminal app in System Settings → Privacy & Security → Bluetooth.
* **Linux:** Install BlueZ: `sudo apt install bluez`. Ensure the adapter is up: `sudo hciconfig hci0 up`.
* **Docker:** BLE is not available in Docker containers. Use a native install for hardware features.

### Memory Database Locked

```
Error: database is locked
```

Another FERAL process is holding the SQLite lock. Stop all instances and retry:

```bash theme={null}
feral stop
feral start
```

If the issue persists, the database file may be corrupted:

```bash theme={null}
cp ~/.feral/memory.db ~/.feral/memory.db.backup
sqlite3 ~/.feral/memory.db "PRAGMA integrity_check;"
```

### Voice Not Activating

**Checklist:**

1. Voice enabled? → `FERAL_VOICE_ENABLED=true`
2. Microphone permission granted to terminal?
3. Wake word set? → Default is `"hey feral"`
4. Audio input device correct? → `FERAL_AUDIO_INPUT=default`

Test audio input:

```bash theme={null}
python -c "import pyaudio; p = pyaudio.PyAudio(); print(p.get_default_input_device_info())"
```

## Still Stuck?

If none of the above resolves your issue:

1. Run `feral doctor` and copy the full output
2. Check logs at `~/.feral/logs/brain.log`
3. Open an issue on [GitHub](https://github.com/FERAL-AI/FERAL-AI/issues) with the doctor output and relevant logs