Troubleshooting

Common issues and how to fix them.

Windows Defender Blocking OpenCrabs

Windows Defender may flag opencrabs.exe as suspicious because it’s an unsigned binary that executes shell commands and makes network requests. This is a false positive.

Add an exclusion:

1. Open Windows Security → Virus & threat protection
2. Virus & threat protection settings → Manage settings
3. Exclusions → Add or remove exclusions
4. Add an exclusion → File → select opencrabs.exe

Or via PowerShell (admin):

Add-MpPreference -ExclusionPath "C:\path\to\opencrabs.exe"

If SmartScreen blocks the first run, click More info → Run anyway.

Binary Won’t Start or Crashes

Startup Errors

Run with debug logging to see what’s failing:

opencrabs -d chat

Logs are written to ~/.opencrabs/logs/.

Download a Previous Version

If the latest release crashes on your machine, download a previous working version from GitHub Releases:

# List all releases
gh release list -R adolfousier/opencrabs

# Download a specific version
gh release download v0.2.66 -R adolfousier/opencrabs -p "opencrabs-*$(uname -m)*$(uname -s | tr A-Z a-z)*"

/evolve — Update & Rollback

/evolve downloads the latest release from GitHub and hot-swaps the binary. It has built-in safety checks:

1. Download — Fetches the platform-specific binary from GitHub Releases
2. Pre-swap health check — Runs opencrabs health-check on the new binary (10s timeout). If it fails, the new binary is deleted and your current version stays untouched.
3. Backup — Creates a backup at <binary-path>.evolve_backup
4. Atomic swap — Replaces the current binary
5. Post-swap health check — Verifies the swapped binary works. If it fails, auto-rolls back to the backup.
6. Restart — exec()-restarts into the new version
7. Brain update prompt — After restart, your crab announces the new version, diffs brain templates against your local files, and offers to update them

If /evolve Fails

The most common reason is the health check caught an issue — your current version stays safe. If something went wrong after the swap:

# Restore the backup manually
cp /path/to/opencrabs.evolve_backup /path/to/opencrabs
chmod +x /path/to/opencrabs

Cargo Install Fallback

When /evolve uses cargo install (building from source), it tries the stable toolchain first. If that fails, it automatically falls back to cargo +nightly. The progress message shows which toolchain succeeded.

Check-Only Mode

The agent can check for updates without installing:

/evolve check_only=true

Bash Tool Safety

The bash tool includes a hard command blocklist that prevents catastrophic commands even if accidentally approved:

• rm -rf /, sudo rm -rf .
• mkfs, dd to /dev/
• Fork bombs
• /etc overwrites, /proc writes
• Sensitive file exfiltration
• Crypto mining commands

These are blocked at the tool level — no configuration needed.

Older CPUs (Pre-2011 / No AVX)

Some features require AVX/AVX2 instructions. Since v0.2.67, OpenCrabs detects CPU capabilities at runtime and automatically hides unavailable options in the onboarding wizard.

What’s Affected

Symptoms

• Local STT option doesn’t appear in /onboard:voice — your CPU lacks AVX2
• Local TTS (Piper) should always be available — no CPU restrictions, works on machines as old as 2007
• Memory search falls back to text-only FTS silently
• Crash with “illegal instruction” on very old CPUs

Fix: Build from Source with CPU Targeting

# For your specific CPU (best performance)
RUSTFLAGS="-C target-cpu=native" cargo build --release

# For Sandy Bridge (AVX but no AVX2)
RUSTFLAGS="-C target-cpu=sandybridge" cargo build --release

macOS with Apple Silicon

Local STT uses Metal GPU acceleration on macOS — no CPU flags needed. Works out of the box on M1/M2/M3/M4.

Config Issues

Config Won’t Load

If config.toml has a syntax error, OpenCrabs will fail to start. Restore from backup:

# Check if a backup exists
ls ~/.opencrabs/config.toml.backup

# Restore it
cp ~/.opencrabs/config.toml.backup ~/.opencrabs/config.toml

Or reinitialize with defaults:

opencrabs init --force

Warning: --force overwrites your config. Back up keys.toml first — it contains your API keys.

Manual Backup

Always keep a backup of your critical files:

cp ~/.opencrabs/config.toml ~/.opencrabs/config.toml.backup
cp ~/.opencrabs/keys.toml ~/.opencrabs/keys.toml.backup
cp ~/.opencrabs/commands.toml ~/.opencrabs/commands.toml.backup

Channel Issues

Telegram

Bot not responding:

1. Verify token from @BotFather is in keys.toml
2. Check your numeric user ID is in allowed_users
3. If respond_to = "mention", you must @mention the bot in groups

Regenerate bot token:

1. Open @BotFather on Telegram
2. /mybots → select bot → API Token → Revoke
3. Copy new token to keys.toml under [channels.telegram]
4. Restart OpenCrabs

Re-setup from scratch: Run /onboard:channels in the TUI.

Telegram Won’t Connect / Reconnect

If the Telegram bot stops responding or you need to re-link it, re-run the channels setup and re-confirm the token + your numeric user ID.

Fix:

1. Run /onboard:channels (TUI: opens the wizard; on a channel: the agent walks you through it).
2. Paste your bot token again if it’s missing (get it from @BotFather).
3. Paste your numeric user ID and hit Enter to confirm.
4. If the bot sends you a message on Telegram, it worked.

On a channel you can do it in one line: /onboard:channels telegram <BOT_TOKEN> <YOUR_NUMERIC_ID>.

Why you have to provide your numeric ID: Telegram’s Bot API exposes only the bot’s identity from a token (via getMe) — it has no way to reveal who created the bot in BotFather. A bot only learns a human’s ID when that human messages it. The onboarding wizard auto-detects your ID via getUpdates when you leave the field blank, but that only works if (a) you’ve already messaged the bot and (b) the bot isn’t already running and consuming those updates — which is exactly the case during a reconnect. So on reconnect, message the bot first, or just paste the ID (get it from @userinfobot).

WhatsApp

QR code / session expired:

WhatsApp sessions are stored at ~/.opencrabs/whatsapp/session.db. To reconnect:

# Delete the session file
rm ~/.opencrabs/whatsapp/session.db

# Re-pair via onboarding
opencrabs chat --onboard

Or press R on the WhatsApp onboarding screen to reset and get a fresh QR code.

Messages not received:

• Verify phone number is in allowed_phones using E.164 format: "+15551234567"
• Empty allowed_phones = [] means accept from everyone

WhatsApp Won’t Connect / Wrong Number Replying

Each OpenCrabs instance supports one WhatsApp account (one companion device). If you connected multiple numbers or the wrong number is replying, you need a full reset. The bot always uses the last number you connected.

Critical: Always reset the connection before connecting a new number. OpenCrabs only keeps the last paired number.

Full reset steps:

1. Remove ALL linked devices from WhatsApp. Open WhatsApp on your phone, go to Settings > Linked Devices, and remove every device in the list. Don’t bother hunting for the opencrabs one. A stale device left over from an earlier pairing is the usual reason the old number keeps replying, so the reliable fix is to clear them all and start fresh.
2. Reset the connection in OpenCrabs — in the TUI or from a channel, go to /onboard:channels and press R to reset the WhatsApp connection. Wait for confirmation that the reset is complete.
3. Re-pair from scratch — after the reset is confirmed, go to WhatsApp > Settings > Linked Devices > Link a Device and scan the new QR code shown by OpenCrabs.

If the bot still shows the old number after resetting, make sure you completed step 1 (removing the device from WhatsApp) before step 2.

Common issues:

Discord

Bot not receiving messages:

1. Ensure Message Content Intent is enabled in Discord Developer Portal → Bot settings
2. Required intents: gateway, guild_messages, direct_messages, message_content
3. Use the bot token (starts with MTk...), not the application ID

Regenerate token: Discord Developer Portal → Bot → Regenerate Token

Slack

Both tokens required:

• Bot token (xoxb-...): For sending messages
• App token (xapp-...): For Socket Mode (receiving events)

Without the app token, the bot can send but not receive messages.

Socket Mode: Must be enabled in app settings → Features → Socket Mode → ON

Trello

Setup:

1. Get API key: trello.com/app-key
2. Generate token from the same page
3. Add board_ids to config — the bot only monitors listed boards
4. Set poll_interval_secs > 0 to enable polling (default 0 = disabled)

General: Re-run Channel Setup

For any channel issues, re-run the onboarding wizard:

opencrabs chat --onboard

Or type /onboard:channels in the TUI.

Agent Hallucinating Tool Calls

If the agent starts sending tool call approvals that don’t render in the UI — meaning it believes it executed actions that never actually ran — the session context has become corrupted.

Fix: Start a new session.

1. Press / and type sessions (or navigate to the Sessions panel)
2. Press N to create a new session
3. Continue your work in the fresh session

This reliably resolves the issue. A fix is coming in a future release.

Daemon Stays Down

If opencrabs service status says stopped:

1. Did you open the TUI? Opening opencrabs deliberately shuts the daemon down so the interactive session can own the channels. The daemon stays down until you opencrabs service start again.
2. Old builds may still have Restart=on-failure instead of Restart=always. Re-generate the unit with opencrabs service install (then service start) to pick up the always-restart policy.
3. Config, keys, commands, and tools hot-reload at runtime. Editing config.toml or keys.toml never needs a daemon restart. If a change isn’t taking effect, check the logs for a ConfigWatcher: reloaded line rather than restarting.

For full daemon/service documentation, see CLI Commands: Daemon Mode vs TUI.

Local STT (Speech-to-Text)

Since v0.2.67, local STT uses rwhisper (candle, pure Rust) instead of whisper-rs/ggml. On macOS, it uses Metal GPU acceleration automatically.

Models

Models download automatically from HuggingFace on first use.

Common Issues

Local STT option not showing in wizard: Your CPU lacks AVX2. Use API mode (Groq Whisper) instead, or build from source with RUSTFLAGS="-C target-cpu=native".

“No audio samples decoded”: Audio file is corrupt or unsupported format. Supported: OGG/Opus, WAV.

Transcription hangs: Times out after 300 seconds. Try a smaller model (quantized-tiny).

Model download fails: Check network connection. Models are fetched from HuggingFace.

Audio too short: Messages under 1 second are automatically padded to prevent tensor errors.

Disabling

[voice]
stt_enabled = false

Local TTS (Text-to-Speech)

Requirements

• Python 3 must be installed and in PATH
• Piper installs automatically in a venv at ~/.opencrabs/models/piper/venv/

Voices

Common Issues

“python3 -m venv failed”: Install Python 3. On Ubuntu: sudo apt install python3 python3-venv. On macOS: brew install python3.

“pip install piper-tts failed”: Network issue or pip corrupted. Fix pip first:

python3 -m pip install --upgrade pip

Telegram voice messages show no waveform: This was fixed in v0.2.64 — audio is now properly encoded as OGG/Opus (RFC 7845). Update to latest version.

Voice preview not playing: Preview uses afplay (macOS), aplay (Linux), or powershell (Windows). Ensure audio output is available.

Re-setup

Run /onboard:voice in the TUI to reconfigure STT/TTS mode and re-download models.

Disabling

[voice]
tts_mode = "off"

Local Embeddings (Memory Search)

The memory search engine uses a ~300 MB embedding model (llama.cpp) for semantic search. It requires AVX on x86 CPUs.

Fallback

If embeddings can’t initialize (no AVX, download failed, disk full), memory search falls back to FTS-only (keyword matching). It still works, just less semantic.

Fix for Older CPUs

Build from source with CPU targeting (see Older CPUs above).

Model Location

Models are stored in ~/.local/share/opencrabs/models/ (platform-specific data directory).

Database Issues

Location

• Main database: ~/.opencrabs/opencrabs.db (SQLite + WAL)
• WhatsApp session: ~/.opencrabs/whatsapp/session.db

Database Corruption

SQLite with WAL mode is very resilient, but if corruption occurs:

# Back up the corrupted file first
cp ~/.opencrabs/opencrabs.db ~/.opencrabs/opencrabs.db.corrupt

# Reinitialize (WARNING: loses all history)
opencrabs db init

Migration Errors

The database automatically migrates on startup (11 migrations). If migrating from an older version with sqlx, the transition is handled automatically — no manual steps needed.

Building from Source

Quick Setup

curl -fsSL https://raw.githubusercontent.com/adolfousier/opencrabs/main/scripts/setup.sh | bash
git clone https://github.com/adolfousier/opencrabs.git && cd opencrabs
cargo build --release

Build Without Voice (Smaller Binary)

cargo build --release --no-default-features --features telegram,whatsapp,discord,slack,trello

Feature Flags

Debug Mode

Run with -d for verbose logging:

opencrabs -d chat

Logs go to ~/.opencrabs/logs/ with 7-day retention.