Troubleshooting

Common things that go wrong, in order of how often we see them.

JARVIS doesn't reply on Telegram

openclaw status
tail -f ~/.openclaw/logs/gateway.log
# Send a Telegram message, should see "[telegram] update received"

Log shows…	Fix
Nothing when you message	Bot token wrong, OR you haven't started a conversation. Open Telegram, find your bot, click START.
`[telegram] 401 Unauthorized`	Bot token wrong. Re-check BotFather, update `~/.openclaw/openclaw.json`.
`[telegram] 403 Forbidden: bot blocked`	You blocked the bot. Open the chat, /restart or unblock.
Update received but no reply	Model error. Look further in the log.

"402 Insufficient Balance" / model failures

Open the dashboard, click BRAIN tab, look at MODEL USAGE panel. You'll see per-model success/failure counts.

Error	Fix
`402 Insufficient Balance`	Top up at provider's billing page
`401 Unauthorized`	API key revoked. Update via `openclaw config set env.<KEY> <value>`
`429 Too Many Requests`	Hit plan rate limit. Wait or upgrade.
`503 Service Unavailable`	Provider outage. Auto-failover via fallback chain.

Brain visualization is empty / dark

Add ?brainDebug=1 to the URL, see the init log overlay.

Symptom	Fix
`Three.js NOT loaded`	CDN unreachable. Check internet OR vendor it locally.
`brain mesh load failed`	Verify `~/.nemoclaw/assets/brain.gltf` exists. Re-run setup.sh.
`fetch FAILED`	Webhook server not running. `cd ~/.nemoclaw && npm start`
`neurons=0`	Backfill didn't run. `python3 ~/.openclaw/workspace/scripts/synapse-engine.py --backfill`

Activations counter stays at 0

Verify the 3 brain crons are installed:

crontab -l | grep synapse
# Should show 3 lines (jarvis-tap, obsidian-tap, ambient-pulse)

Dashboard won't load (502 / TLS / refused)

Cert error: click "Advanced" → "Proceed" first time. Self-signed.
Connection refused: dashboard isn't running. cd ~/.nemoclaw && npm start
502: dashboard crashed. Check terminal output.

Model fallback cascade (everything failing)

grep "fallback" ~/.openclaw/logs/gateway.log | tail -30

Add a final Ollama fallback for resilience:

ollama pull qwen2.5:7b   # 4.5GB, runs anywhere
# In openclaw.json fallbacks: ["...your usual chain...", "ollama/qwen2.5:7b"]

Memory issues

Symptom	Fix
JARVIS forgot what we just talked about	`openclaw session reset main`
JARVIS knows things I never told it	`grep -r "the thing" ~/.openclaw/agents//sessions/.compaction.json ~/.openclaw/workspace/MEMORY.md`
Context window exhausted	`openclaw session compact main`

"openclaw start" exits immediately

Symptom	Fix
Port 18789 in use	`lsof -i :18789` to find + kill
`EACCES: permission denied`	`chown -R $USER ~/.openclaw`
`MODULE_NOT_FOUND`	`npm install -g openclaw --force`
Configuration validation failed	`python3 -m json.tool ~/.openclaw/openclaw.json`

Disk fills up

# Old session jsonls
find ~/.openclaw/agents/*/sessions/ -name "*.deleted.*" -mtime +30 -delete

# Trade bot logs
truncate -s 0 ~/jarvis-kit-extras/trading-bot/data/*.log

# Cron run logs
find ~/.openclaw/cron/runs/ -name "*.jsonl" -mtime +60 -delete

Where to look when nothing matches above

# Main log
tail -200 ~/.openclaw/logs/gateway.log

# Webhook server (dashboard)
# Output goes to terminal where you ran npm start

# Brain SQLite manual inspection
sqlite3 ~/.openclaw/workspace/data/synapse-graph.sqlite "
  SELECT region, COUNT(*) FROM neurons GROUP BY region;
  SELECT trigger_type, COUNT(*) FROM activations
    WHERE fired_at > strftime('%s','now') - 3600 GROUP BY trigger_type;
"