Skip to main content

​
Troubleshooting 🔧

When crocbot misbehaves, here’s how to fix it. Start with the FAQ’s First 60 seconds if you just want a quick triage recipe. This page goes deeper on runtime failures and diagnostics. Provider-specific shortcuts: /channels/troubleshooting

​
Status & Diagnostics

Quick triage commands (in order):
CommandWhat it tells youWhen to use it
crocbot statusLocal summary: OS + update, gateway reachability/mode, service, agents/sessions, provider config stateFirst check, quick overview
crocbot status --allFull local diagnosis (read-only, pasteable, safe-ish) incl. log tailWhen you need to share a debug report
crocbot status --deepRuns gateway health checks (incl. provider probes; requires reachable gateway)When “configured” doesn’t mean “working”
crocbot gateway probeGateway discovery + reachability (local + remote targets)When you suspect you’re probing the wrong gateway
crocbot channels status --probeAsks the running gateway for channel status (and optionally probes)When gateway is reachable but channels misbehave
crocbot gateway statusSupervisor state (launchd/systemd/schtasks), runtime PID/exit, last gateway errorWhen the service “looks loaded” but nothing runs
crocbot logs --followLive logs (best signal for runtime issues)When you need the actual failure reason
Sharing output: prefer crocbot status --all (it redacts tokens). If you paste crocbot status, consider setting CROCBOT_SHOW_SECRETS=0 first (token previews). See also: Health checks and Logging.

​
Common Issues

​
No API key found for provider “anthropic”

This means the agent’s auth store is empty or missing Anthropic credentials. Auth is per agent, so a new agent won’t inherit the main agent’s keys. Fix options:
  • Re-run onboarding and choose Anthropic for that agent.
  • Or paste a setup-token on the gateway host: 
    crocbot models auth setup-token --provider anthropic
  • Or copy auth-profiles.json from the main agent dir to the new agent dir.
Verify: 
crocbot models status

​
OAuth token refresh failed (Anthropic Claude subscription)

This means the stored Anthropic OAuth token expired and the refresh failed. If you’re on a Claude subscription (no API key), the most reliable fix is to switch to a Claude Code setup-token and paste it on the gateway host. Recommended (setup-token): 
# Run on the gateway host (paste the setup-token)
crocbot models auth setup-token --provider anthropic
crocbot models status
If you generated the token elsewhere: 
crocbot models auth paste-token --provider anthropic
crocbot models status
More detail: Anthropic and OAuth.

​
Control UI fails on HTTP (“device identity required” / “connect failed”)

If you open the dashboard over plain HTTP (e.g. http://<lan-ip>:18789/ or http://<tailscale-ip>:18789/), the browser runs in a non-secure context and blocks WebCrypto, so device identity can’t be generated. Fix:
  • Prefer HTTPS via Tailscale Serve.
  • Or open locally on the gateway host: http://127.0.0.1:18789/.
  • If you must stay on HTTP, enable gateway.controlUi.allowInsecureAuth: true and use a gateway token (token-only; no device identity). See Control UI.

​
CI Secrets Scan Failed

This means detect-secrets found new candidates not yet in the baseline. Follow Secret scanning.

​
Service Installed but Nothing is Running

If the gateway service is installed but the process exits immediately, the service can appear “loaded” while nothing is running. Check: 
crocbot gateway status
crocbot doctor
Doctor/service will show runtime state (PID/last exit) and log hints. Logs:
  • Preferred: crocbot logs --follow
  • File logs (always): /tmp/crocbot/crocbot-YYYY-MM-DD.log (or your configured logging.file)
  • LaunchAgent (if installed): $CROCBOT_STATE_DIR/logs/gateway.log and gateway.err.log
  • Linux systemd (if installed): journalctl --user -u crocbot-gateway[-<profile>].service -n 200 --no-pager
  • Windows: schtasks /Query /TN "crocbot Gateway (<profile>)" /V /FO LIST
Enable more logging:
  • Bump file log detail (persisted JSONL): 
    { "logging": { "level": "debug" } }
  • Bump console verbosity (TTY output only): 
    { "logging": { "consoleLevel": "debug", "consoleStyle": "pretty" } }
  • Quick tip: --verbose affects console output only. File logs remain controlled by logging.level.
See /help/logging for a full overview of formats, config, and access.

​
”Gateway start blocked: set gateway.mode=local”

This means the config exists but gateway.mode is unset (or not local), so the Gateway refuses to start. Fix (recommended):
  • Run the wizard and set the Gateway run mode to Local: 
    crocbot configure
  • Or set it directly: 
    crocbot config set gateway.mode local
If you meant to run a remote Gateway instead:
  • Set a remote URL and keep gateway.mode=remote: 
    crocbot config set gateway.mode remote
crocbot config set gateway.remote.url "wss://gateway.example.com"
Ad-hoc/dev only: pass --allow-unconfigured to start the gateway without gateway.mode=local. No config file yet? Run crocbot setup to create a starter config, then rerun the gateway.

​
Service Environment (PATH + runtime)

The gateway service runs with a minimal PATH to avoid shell/manager cruft:
  • Linux: /usr/local/bin, /usr/bin, /bin
This intentionally excludes version managers (nvm/fnm/volta/asdf) and package managers (pnpm/npm) because the service does not load your shell init. Runtime variables like DISPLAY should live in ~/.crocbot/.env (loaded early by the gateway). Exec runs on host=gateway merge your login-shell PATH into the exec environment, so missing tools usually mean your shell init isn’t exporting them (or set tools.exec.pathPrepend). See /tools/exec. Telegram channels require Node; Bun is unsupported. If your service was installed with Bun or a version-managed Node path, run crocbot doctor to migrate to a system Node install.

​
Skill missing API key in sandbox

Symptom: Skill works on host but fails in sandbox with missing API key. Why: sandboxed exec runs inside Docker and does not inherit host process.env. Fix:
  • set agents.defaults.sandbox.docker.env (or per-agent agents.list[].sandbox.docker.env)
  • or bake the key into your custom sandbox image
  • then run crocbot sandbox recreate --agent <id> (or --all)

​
Service Running but Port Not Listening

If the service reports running but nothing is listening on the gateway port, the Gateway likely refused to bind. What “running” means here
  • Runtime: running means your supervisor (launchd/systemd/schtasks) thinks the process is alive.
  • RPC probe means the CLI could actually connect to the gateway WebSocket and call status.
  • Always trust Probe target: + Config (service): as the “what did we actually try?” lines.
Check:
  • gateway.mode must be local for crocbot gateway and the service.
  • If you set gateway.mode=remote, the CLI defaults to a remote URL. The service can still be running locally, but your CLI may be probing the wrong place. Use crocbot gateway status to see the service’s resolved port + probe target (or pass --url).
  • crocbot gateway status and crocbot doctor surface the last gateway error from logs when the service looks running but the port is closed.
  • Non-loopback binds (lan/tailnet/custom, or auto when loopback is unavailable) require auth: gateway.auth.token (or CROCBOT_GATEWAY_TOKEN).
  • gateway.remote.token is for remote CLI calls only; it does not enable local auth.
  • gateway.token is ignored; use gateway.auth.token.
If crocbot gateway status shows a config mismatch
  • Config (cli): ... and Config (service): ... should normally match.
  • If they don’t, you’re almost certainly editing one config while the service is running another.
  • Fix: rerun crocbot gateway install --force from the same --profile / CROCBOT_STATE_DIR you want the service to use.
If crocbot gateway status reports service config issues
  • The supervisor config (launchd/systemd/schtasks) is missing current defaults.
  • Fix: run crocbot doctor to update it (or crocbot gateway install --force for a full rewrite).
If Last gateway error: mentions “refusing to bind … without auth”
  • You set gateway.bind to a non-loopback mode (lan/tailnet/custom, or auto when loopback is unavailable) but didn’t configure auth.
  • Fix: set gateway.auth.mode + gateway.auth.token (or export CROCBOT_GATEWAY_TOKEN) and restart the service.
If crocbot gateway status says bind=tailnet but no tailnet interface was found
  • The gateway tried to bind to a Tailscale IP (100.64.0.0/10) but none were detected on the host.
  • Fix: bring up Tailscale on that machine (or change gateway.bind to loopback/lan).
If Probe note: says the probe uses loopback
  • That’s expected for bind=lan: the gateway listens on 0.0.0.0 (all interfaces), and loopback should still connect locally.
  • For remote clients, use a real LAN IP (not 0.0.0.0) plus the port, and ensure auth is configured.

​
Address Already in Use (Port 18789)

This means something is already listening on the gateway port. Check: 
crocbot gateway status
It will show the listener(s) and likely causes (gateway already running, SSH tunnel). If needed, stop the service or pick a different port.

​
Extra Workspace Folders Detected

If you upgraded from older installs, you might still have ~/crocbot on disk. Multiple workspace directories can cause confusing auth or state drift because only one workspace is active. Fix: keep a single active workspace and archive/remove the rest. See Agent workspace.

​
Main chat running in a sandbox workspace

Symptoms: pwd or file tools show ~/.crocbot/sandboxes/... even though you expected the host workspace. Why: agents.defaults.sandbox.mode: "non-main" keys off session.mainKey (default "main"). Group/channel sessions use their own keys, so they are treated as non-main and get sandbox workspaces. Fix options:
  • If you want host workspaces for an agent: set agents.list[].sandbox.mode: "off".
  • If you want host workspace access inside sandbox: set workspaceAccess: "rw" for that agent.

​
”Agent was aborted”

The agent was interrupted mid-response. Causes:
  • User sent stop, abort, esc, wait, or exit
  • Timeout exceeded
  • Process crashed
Fix: Just send another message. The session continues.

​
”Agent failed before reply: Unknown model: anthropic/claude-haiku-3-5”

crocbot intentionally rejects older/insecure models (especially those more vulnerable to prompt injection). If you see this error, the model name is no longer supported. Fix:
  • Pick a latest model for the provider and update your config or model alias.
  • If you’re unsure which models are available, run crocbot models list or crocbot models scan and choose a supported one.
  • Check gateway logs for the detailed failure reason.
See also: Models CLI and Model providers.

​
Messages Not Triggering

Check 1: Is the sender allowlisted? 
crocbot status
Look for AllowFrom: ... in the output. Check 2: For group chats, is mention required? 
# The message must match mentionPatterns or explicit mentions; defaults live in channel groups/guilds.
# Multi-agent: `agents.list[].groupChat.mentionPatterns` overrides global patterns.
grep -n "agents\\|groupChat\\|mentionPatterns\\|channels\\.telegram\\.groups" \
  "${CROCBOT_CONFIG_PATH:-$HOME/.crocbot/crocbot.json}"
Check 3: Check the logs 
crocbot logs --follow
# or if you want quick filters:
tail -f "$(ls -t /tmp/crocbot/crocbot-*.log | head -1)" | grep "blocked\\|skip\\|unauthorized"

​
DM blocked (allowlist)

If dmPolicy is allowlist, unknown senders are ignored until they are added. Check:
  • Confirm channels.telegram.allowFrom contains your user ID.
  • Confirm channels.telegram.dmPolicy is allowlist or open as intended.

​
Image + Mention Not Working

In some cases, when you send an image with ONLY a mention (no other text), mention metadata may not be included. Workaround: Add some text with the mention:
  • ❌ @croc + image
  • ✅ @croc check this + image

​
Session Not Resuming

Check 1: Is the session file there? 
ls -la ~/.crocbot/agents/<agentId>/sessions/
Check 2: Is the reset window too short? 
{
  "session": {
    "reset": {
      "mode": "daily",
      "atHour": 4,
      "idleMinutes": 10080  // 7 days
    }
  }
}
Check 3: Did someone send /new, /reset, or a reset trigger?

​
Agent Timing Out

Default timeout is 30 minutes. For long tasks: 
{
  "reply": {
    "timeoutSeconds": 3600  // 1 hour
  }
}
Or use the process tool to background long commands.

​
Channel Disconnected

# Check local status (creds, sessions, queued events)
crocbot status
# Probe the running gateway + channels
crocbot status --deep

# View recent connection events
crocbot logs --limit 200 | grep "connection\\|disconnect\\|logout"
Fix: Usually reconnects automatically once the Gateway is running. If you’re stuck, restart the Gateway process (however you supervise it), or run it manually with verbose output: 
crocbot gateway --verbose
If you’re logged out / unlinked: 
crocbot channels logout
trash "${CROCBOT_STATE_DIR:-$HOME/.crocbot}/credentials" # if logout can't cleanly remove everything
crocbot channels login --verbose

​
Media Send Failing

Check 1: Is the file path valid? 
ls -la /path/to/your/image.jpg
Check 2: Is it too large?
  • Images: max 6MB
  • Audio/Video: max 16MB
  • Documents: max 100MB
Check 3: Check media logs 
grep "media\\|fetch\\|download" "$(ls -t /tmp/crocbot/crocbot-*.log | head -1)" | tail -20

​
High Memory Usage

crocbot keeps conversation history in memory. Fix: Restart periodically or set session limits: 
{
  "session": {
    "historyLimit": 100  // Max messages to keep
  }
}

​
Common troubleshooting

​
“Gateway won’t start — configuration invalid”

crocbot now refuses to start when the config contains unknown keys, malformed values, or invalid types. This is intentional for safety. Fix it with Doctor: 
crocbot doctor
crocbot doctor --fix
Notes:
  • crocbot doctor reports every invalid entry.
  • crocbot doctor --fix applies migrations/repairs and rewrites the config.
  • Diagnostic commands like crocbot logs, crocbot health, crocbot status, crocbot gateway status, and crocbot gateway probe still run even if the config is invalid.

​
“All models failed” — what should I check first?

  • Credentials present for the provider(s) being tried (auth profiles + env vars).
  • Model routing: confirm agents.defaults.model.primary and fallbacks are models you can access.
  • Gateway logs in /tmp/crocbot/… for the exact provider error.
  • Model status: use /model status (chat) or crocbot models status (CLI).

​
Build errors on main — what’s the standard fix path?

  1. git pull origin main && pnpm install
  2. crocbot doctor
  3. Check GitHub issues
  4. Temporary workaround: check out an older commit

​
npm install fails (allow-build-scripts / missing tar or yargs). What now?

If you’re running from source, use the repo’s package manager: pnpm (preferred). The repo declares packageManager: "pnpm@…". Typical recovery: 
git status   # ensure you’re in the repo root
pnpm install
pnpm build
crocbot doctor
crocbot gateway restart
Why: pnpm is the configured package manager for this repo.

​
How do I switch between git installs and npm installs?

Use the website installer and select the install method with a flag. It upgrades in place and rewrites the gateway service to point at the new install. Switch to git install: 
curl -fsSL https://github.com/moshehbenavraham/crocbot/install.sh | bash -s -- --install-method git --no-onboard
Switch to npm global: 
curl -fsSL https://github.com/moshehbenavraham/crocbot/install.sh | bash
Notes:
  • The git flow only rebases if the repo is clean. Commit or stash changes first.
  • After switching, run: 
    crocbot doctor
crocbot gateway restart

​
Telegram block streaming isn’t splitting text between tool calls. Why?

Block streaming only sends completed text blocks. Common reasons you see a single message:
  • agents.defaults.blockStreamingDefault is still "off".
  • channels.telegram.blockStreaming is set to false.
  • channels.telegram.streamMode is partial or block and draft streaming is active (private chat + topics). Draft streaming disables block streaming in that case.
  • Your minChars / coalesce settings are too high, so chunks get merged.
  • The model emits one large text block (no mid‑reply flush points).
Fix checklist:
  1. Put block streaming settings under agents.defaults, not the root.
  2. Set channels.telegram.streamMode: "off" if you want real multi‑message block replies.
  3. Use smaller chunk/coalesce thresholds while debugging.
See Streaming.

​
Cloud Code Assist API error: invalid tool schema (400). What now?

This is almost always a tool schema compatibility issue. The Cloud Code Assist endpoint accepts a strict subset of JSON Schema. crocbot scrubs/normalizes tool schemas in current main, but the fix is not in the last release yet (as of January 13, 2026). Fix checklist:
  1. Update crocbot:
    • If you can run from source, pull main and restart the gateway.
    • Otherwise, wait for the next release that includes the schema scrubber.
  2. Avoid unsupported keywords like anyOf/oneOf/allOf, patternProperties, additionalProperties, minLength, maxLength, format, etc.
  3. If you define custom tools, keep the top‑level schema as type: "object" with properties and simple enums.
See Tools and TypeBox schemas.

​
Gateway stuck on “Starting…”

The client connects to a local gateway on port 18789. If it stays stuck: Fix 1: Stop the supervisor (preferred) If the gateway is supervised by systemd, killing the PID will just respawn it. Stop the supervisor first: 
crocbot gateway status
crocbot gateway stop
Fix 2: Port is busy (find the listener) 
lsof -nP -iTCP:18789 -sTCP:LISTEN
If it’s an unsupervised process, try a graceful stop first, then escalate: 
kill -TERM <PID>
sleep 1
kill -9 <PID> # last resort
Fix 3: Check the CLI install Ensure the global crocbot CLI is installed: 
crocbot --version
npm install -g crocbot@<version>

​
Debug Mode

Get verbose logging: 
# Turn on trace logging in config:
#   ${CROCBOT_CONFIG_PATH:-$HOME/.crocbot/crocbot.json} -> { logging: { level: "trace" } }
#
# Then run verbose commands to mirror debug output to stdout:
crocbot gateway --verbose
crocbot channels login --verbose

​
Log Locations

LogLocation
Gateway file logs (structured)/tmp/crocbot/crocbot-YYYY-MM-DD.log (or logging.file)
Gateway service logs (supervisor)Linux: journalctl --user -u crocbot-gateway[-<profile>].service -n 200 --no-pager
Session files$CROCBOT_STATE_DIR/agents/<agentId>/sessions/
Media cache$CROCBOT_STATE_DIR/media/
Credentials$CROCBOT_STATE_DIR/credentials/

​
Health Check

# Supervisor + probe target + config paths
crocbot gateway status
# Include system-level scans (legacy/extra services, port listeners)
crocbot gateway status --deep

# Is the gateway reachable?
crocbot health --json
# If it fails, rerun with connection details:
crocbot health --verbose

# Is something listening on the default port?
lsof -nP -iTCP:18789 -sTCP:LISTEN

# Recent activity (RPC log tail)
crocbot logs --follow
# Fallback if RPC is down
tail -20 /tmp/crocbot/crocbot-*.log

​
Reset Everything

Nuclear option: 
crocbot gateway stop
# If you installed a service and want a clean install:
# crocbot gateway uninstall

trash "${CROCBOT_STATE_DIR:-$HOME/.crocbot}"
crocbot channels login         # re-authenticate
crocbot gateway restart           # or: crocbot gateway
Warning: This loses all sessions and requires re-authentication.

​
Getting Help

  1. Check logs first: /tmp/crocbot/ (default: crocbot-YYYY-MM-DD.log, or your configured logging.file)
  2. Search existing issues on GitHub
  3. Open a new issue with:
    • crocbot version
    • Relevant log snippets
    • Steps to reproduce
    • Your config (redact secrets!)
“Have you tried turning it off and on again?” — Every IT person ever 🦞🔧

​
Browser Not Starting (Linux)

If you see "Failed to start Chrome CDP on port 18800": Most likely cause: Snap-packaged Chromium on Ubuntu. Quick fix: Install Google Chrome instead: 
wget https://dl.google.com/linux/direct/google-chrome-stable_current_amd64.deb
sudo dpkg -i google-chrome-stable_current_amd64.deb
Then set in config: 
{
  "browser": {
    "executablePath": "/usr/bin/google-chrome-stable"
  }
}
Full guide: See browser-linux-troubleshooting