Troubleshooting

Diagnostic Tool

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

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.

One-liner install
Git clone install
Docker

The installer creates a virtual environment at ~/.feral-env. Activate it:

source ~/.feral-env/bin/activate

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

echo 'source ~/.feral-env/bin/activate' >> ~/.zshrc

echo 'source ~/.feral-env/bin/activate' >> ~/.bashrc

Ensure feral-core is installed in your active Python environment:

cd FERAL-AI/feral-core
pip install -e ".[llm]"
which feral

The feral CLI is not available on the host with Docker installs. Use docker compose exec instead:

docker compose exec brain feral status

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:

feral setup

For quick configuration without the wizard:

export ANTHROPIC_API_KEY=sk-ant-...

export OPENAI_API_KEY=sk-...

# Just ensure Ollama is running:
ollama serve

Ollama is auto-detected on localhost:11434 and requires no API key. It’s the fastest way to get running.

Port 9090 Already in Use

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

Another process is occupying the brain’s default port.

# 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:

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

# 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:

Ensure FERAL is bound on all interfaces:

FERAL_HOST=0.0.0.0 feral start

Regenerate the pairing link in Devices -> Pair new device.
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:

feral access remote-up
feral access status

If needed, complete Tailscale login first:

tailscale up

To revert:

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:

playwright install chromium

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.

pip Install Failures

Symptom: Dependency resolution errors or build failures during install.

Upgrade pip

pip install --upgrade pip setuptools wheel

Use the LLM extras

pip install -e ".[llm]"

Install system dependencies (Linux)

Some packages need system libraries:

sudo apt install build-essential libffi-dev libssl-dev portaudio19-dev

Try a fresh virtual environment

python3.11 -m venv ~/.feral-env-fresh
source ~/.feral-env-fresh/bin/activate
pip install -e ".[llm]"

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:

feral stop
feral start

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

cp ~/.feral/memory.db ~/.feral/memory.db.backup
sqlite3 ~/.feral/memory.db "PRAGMA integrity_check;"

Voice Not Activating

Checklist:

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

Test audio input:

python -c "import pyaudio; p = pyaudio.PyAudio(); print(p.get_default_input_device_info())"

Still Stuck?

If none of the above resolves your issue:

Run feral doctor and copy the full output
Check logs at ~/.feral/logs/brain.log
Open an issue on GitHub with the doctor output and relevant logs

Overview

Getting Started

Guides

Marketplace

Memory

Hardware

Channels

Connectivity

Security

Native Apps

Operations

SDKs

Reference

Help

Community

Troubleshooting

Diagnostic Tool

Common Issues

`command not found: feral`

No LLM Key Configured

Port 9090 Already in Use

WebSocket Connection Refused

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

Anywhere mode selected but pairing still fails

Playwright Chromium Missing

pip Install Failures

BLE Adapter Not Found

Memory Database Locked

Voice Not Activating

Still Stuck?

​Diagnostic Tool

​Common Issues

​command not found: feral

​No LLM Key Configured

​Port 9090 Already in Use

​WebSocket Connection Refused

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

​Anywhere mode selected but pairing still fails

​Playwright Chromium Missing

​pip Install Failures

​BLE Adapter Not Found

​Memory Database Locked

​Voice Not Activating

​Still Stuck?

Diagnostic Tool

Common Issues

`command not found: feral`

No LLM Key Configured

Port 9090 Already in Use

WebSocket Connection Refused

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

Anywhere mode selected but pairing still fails

Playwright Chromium Missing

pip Install Failures

BLE Adapter Not Found

Memory Database Locked

Voice Not Activating

Still Stuck?