Skip to main content

​
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.
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

​
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-...
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:
  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
# Quick connectivity test
curl http://localhost:9090/api/dashboard/status

​
Playwright Chromium Missing

Error: Browser not found. Run 'playwright install chromium'.
FERAL uses Playwright for computer-use features (browser automation, screen capture). Install the browser: 
playwright install chromium
If you don’t need computer-use features, disable them to skip the Playwright requirement:
export FERAL_COMPUTER_USE=false

​
pip Install Failures

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

Upgrade pip

pip install --upgrade pip setuptools wheel
2

Use the LLM extras

pip install -e ".[llm]"
3

Install system dependencies (Linux)

Some packages need system libraries:
sudo apt install build-essential libffi-dev libssl-dev portaudio19-dev
4

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:
  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: 
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 with the doctor output and relevant logs