Troubleshooting 🔧

When Equabot 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):

Command	What it tells you	When to use it
`equabot status`	Local summary: OS + update, gateway reachability/mode, service, agents/sessions, provider config state	First check, quick overview
`equabot status --all`	Full local diagnosis (read-only, pasteable, safe-ish) incl. log tail	When you need to share a debug report
`equabot status --deep`	Runs gateway health checks (incl. provider probes; requires reachable gateway)	When “configured” doesn’t mean “working”
`equabot gateway probe`	Gateway discovery + reachability (local + remote targets)	When you suspect you’re probing the wrong gateway
`equabot channels status --probe`	Asks the running gateway for channel status (and optionally probes)	When gateway is reachable but channels misbehave
`equabot gateway status`	Supervisor state (launchd/systemd/schtasks), runtime PID/exit, last gateway error	When the service “looks loaded” but nothing runs
`equabot logs --follow`	Live logs (best signal for runtime issues)	When you need the actual failure reason

Sharing output: prefer equabot status --all (it redacts tokens). If you paste equabot status, consider setting EQUABOT_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:

equabot models auth setup-token --provider anthropic

Or copy auth-profiles.json from the main agent dir to the new agent dir.

Verify:

equabot 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 or re-sync Claude Code CLI OAuth on the gateway host. Recommended (setup-token):

# Run on the gateway host (runs Claude Code CLI)
equabot models auth setup-token --provider anthropic
equabot models status

If you generated the token elsewhere:

equabot models auth paste-token --provider anthropic
equabot models status

If you want to keep OAuth reuse: log in with Claude Code CLI on the gateway host, then run equabot models status to sync the refreshed token into Equabot’s auth store. 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/pairing). 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:

equabot gateway status
equabot doctor

Doctor/service will show runtime state (PID/last exit) and log hints. Logs:

Preferred: equabot logs --follow
File logs (always): /tmp/equabot/equabot-YYYY-MM-DD.log (or your configured logging.file)
macOS LaunchAgent (if installed): $EQUABOT_STATE_DIR/logs/gateway.log and gateway.err.log
Linux systemd (if installed): journalctl --user -u equabot-gateway[-<profile>].service -n 200 --no-pager
Windows: schtasks /Query /TN "Equabot 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 /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:
```
equabot configure
```
Or set it directly:
```
equabot config set gateway.mode local
```

If you meant to run a remote Gateway instead:

Set a remote URL and keep gateway.mode=remote:

equabot config set gateway.mode remote
equabot 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 equabot 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:

macOS: /opt/homebrew/bin, /usr/local/bin, /usr/bin, /bin
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 ~/.equabot/.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. WhatsApp + Telegram channels require Node; Bun is unsupported. If your service was installed with Bun or a version-managed Node path, run equabot 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 equabot 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 equabot 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 equabot gateway status to see the service’s resolved port + probe target (or pass --url).
equabot gateway status and equabot 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 EQUABOT_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 equabot 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 equabot gateway install --force from the same --profile / EQUABOT_STATE_DIR you want the service to use.

If equabot gateway status reports service config issues

The supervisor config (launchd/systemd/schtasks) is missing current defaults.
Fix: run equabot doctor to update it (or equabot 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 left auth off.
Fix: set gateway.auth.mode + gateway.auth.token (or export EQUABOT_GATEWAY_TOKEN) and restart the service.

If equabot 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.

Unauthorized: Gateway Token Mismatch

If you see this error when the CLI or an agent connects to the Gateway:

unauthorized: gateway token mismatch (set gateway.remote.token to match gateway.auth.token)

it means the token the client sent does not match the token the Gateway expects. How token auth works

The Gateway validates incoming connections against gateway.auth.token (the server-side secret).
The CLI sends gateway.remote.token (the client-side secret) when connecting.
These two values must be identical. If they differ, the Gateway rejects the connection with token_mismatch.

Common causes:

The config was edited to change one token but not the other.
A token rotation updated gateway.auth.token but forgot to update gateway.remote.token (or vice versa).
The config file was updated but the Gateway process is still running with the old config loaded at startup.

Fix:

Open ~/.equabot/equabot.json and verify both tokens match:

{
  gateway: {
    auth: { mode: "token", token: "same-value" },
    remote: { token: "same-value" }
  }
}

If the values already match on disk, the running Gateway may be stale. Check when it started:
```
ps -o pid,lstart -p $(pgrep equabot-gateway)
```
If the start time predates your config change, restart the Gateway. Auth changes require a full Gateway restart (they are not hot-reloaded). See the hot reload matrix for details.
Restart via the Equabot Mac app, scripts/restart-mac.sh, or your platform’s service manager.
Verify:
```
equabot gateway status
```

See also:

Token rotation checklist for the full rotation procedure.
gateway.remote.token is for remote CLI calls only; it does not enable local Gateway auth. Use gateway.auth.token (or EQUABOT_GATEWAY_TOKEN) for that.

Address Already in Use (Port 18789)

This means something is already listening on the gateway port. Check:

equabot 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 ~/equabot 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 ~/.equabot/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

This error means the gateway’s internal model registry does not recognize the model ID. The error is generated locally (not by the provider API). Common causes:

Older/insecure model: Equabot intentionally rejects some older models vulnerable to prompt injection (e.g., claude-haiku-3-5).
Typo or unnormalized ID: Some short model names are auto-normalized (e.g., claude-sonnet-4 resolves to claude-sonnet-4-20250514). If the name is not in the normalization table or the pi-ai catalog, the gateway rejects it.
Provider not configured: The provider prefix (e.g., minimax/) may not have a matching provider config or auth profile.

Fix:

Pick a latest model for the provider and update your config or model alias.
Check the normalization table for your provider (e.g., Anthropic model ID normalization) to see if a shorter name auto-resolves.
Run equabot models list or equabot models scan to see supported models.
Check gateway logs for the detailed failure reason.

See also: Models CLI and Model providers.

Messages Not Triggering

Check 1: Is the sender allowlisted?

equabot 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\\.whatsapp\\.groups\\|channels\\.telegram\\.groups\\|channels\\.imessage\\.groups\\|channels\\.discord\\.guilds" \
  "${EQUABOT_CONFIG_PATH:-$HOME/.equabot/equabot.json}"

Check 3: Check the logs

equabot logs --follow
# or if you want quick filters:
tail -f "$(ls -t /tmp/equabot/equabot-*.log | head -1)" | grep "blocked\\|skip\\|unauthorized"

Pairing Code Not Arriving

If dmPolicy is pairing, unknown senders should receive a code and their message is ignored until approved. Check 1: Is a pending request already waiting?

equabot pairing list <channel>

Pending DM pairing requests are capped at 3 per channel by default. If the list is full, new requests won’t generate a code until one is approved or expires. Check 2: Did the request get created but no reply was sent?

equabot logs --follow | grep "pairing request"

Check 3: Confirm dmPolicy isn’t open/allowlist for that channel.

Image + Mention Not Working

Known issue: When you send an image with ONLY a mention (no other text), WhatsApp sometimes doesn’t include the mention metadata. Workaround: Add some text with the mention:

❌ @equabot + image
✅ @equabot check this + image

Session Not Resuming

Check 1: Is the session file there?

ls -la ~/.equabot/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?

Stale Session Errors (sessions.resolve)

Symptom: Gateway logs show repeated sessions.resolve failures:

errorCode=INVALID_REQUEST errorMessage=No session found: <uuid>

Why: A cron job, UI client, or subagent references a session key whose entry was deleted or expired from the session store. Cron jobs are the most common source because they persist the session key in ~/.equabot/cron/jobs.json and continue resolving it after the session has been cleaned up. Fix: Step 1: Identify the stale key from logs:

grep "No session found" ~/.equabot/logs/gateway.log | tail -5

Step 2: Check if a cron job references the UUID:

grep "<uuid>" ~/.equabot/cron/jobs.json

Step 3: If a cron job owns the stale reference, remove or update it:

equabot cron remove <jobId>

Or use the Control UI Cron Jobs page to delete the job. Step 4: If the reference comes from a UI client (Control UI session selector, macOS app), refresh the session list. The entry was already removed from the store; the client is using a cached key. Note: Session store entries are recreated on demand when a new message arrives. The errors are harmless (they do not block other operations) but generate log noise. Removing the stale reference stops the errors.

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.

WhatsApp Disconnected

# Check local status (creds, sessions, queued events)
equabot status
# Probe the running gateway + channels (WA connect + Telegram + Discord APIs)
equabot status --deep

# View recent connection events
equabot 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:

equabot gateway --verbose

If you’re logged out / unlinked:

equabot channels logout
trash "${EQUABOT_STATE_DIR:-$HOME/.equabot}/credentials" # if logout can't cleanly remove everything
equabot channels login --verbose       # re-scan QR

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/equabot/equabot-*.log | head -1)" | tail -20

High Memory Usage

Equabot 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”

Equabot now refuses to start when the config contains unknown keys, malformed values, or invalid types. This is intentional for safety. Fix it with Doctor:

equabot doctor
equabot doctor --fix

Notes:

equabot doctor reports every invalid entry.
equabot doctor --fix applies migrations/repairs and rewrites the config.
Diagnostic commands like equabot logs, equabot health, equabot status, equabot gateway status, and equabot 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/equabot/… for the exact provider error.
Model status: use /model status (chat) or equabot models status (CLI).

I’m running on my personal WhatsApp number — why is self-chat weird?

Enable self-chat mode and allowlist your own number:

{
  channels: {
    whatsapp: {
      selfChatMode: true,
      dmPolicy: "allowlist",
      allowFrom: ["+15555550123"]
    }
  }
}

See WhatsApp setup.

WhatsApp logged me out. How do I re‑auth?

Run the login command again and scan the QR code:

equabot channels login

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

git pull origin main && pnpm install
equabot doctor
Check GitHub issues or Discord
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
equabot doctor
equabot 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://equabot.com/install.sh | bash -s -- --install-method git --no-onboard

Switch to npm global:

curl -fsSL https://equabot.com/install.sh | bash

Notes:

The git flow only rebases if the repo is clean. Commit or stash changes first.
After switching, run:
```
equabot doctor
equabot 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:

Put block streaming settings under agents.defaults, not the root.
Set channels.telegram.streamMode: "off" if you want real multi‑message block replies.
Use smaller chunk/coalesce thresholds while debugging.

See Streaming.

Discord doesn’t reply in my server even with `requireMention: false`. Why?

requireMention only controls mention‑gating after the channel passes allowlists. By default channels.discord.groupPolicy is allowlist, so guilds must be explicitly enabled. If you set channels.discord.guilds.<guildId>.channels, only the listed channels are allowed; omit it to allow all channels in the guild. Fix checklist:

Set channels.discord.groupPolicy: "open" or add a guild allowlist entry (and optionally a channel allowlist).
Use numeric channel IDs in channels.discord.guilds.<guildId>.channels.
Put requireMention: false under channels.discord.guilds (global or per‑channel). Top‑level channels.discord.requireMention is not a supported key.
Ensure the bot has Message Content Intent and channel permissions.
Run equabot channels status --probe for audit hints.

Docs: Discord, Channels troubleshooting.

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. Equabot scrubs/normalizes tool schemas in current main, but the fix is not in the last release yet (as of January 13, 2026). Fix checklist:

Update Equabot:
- If you can run from source, pull main and restart the gateway.
- Otherwise, wait for the next release that includes the schema scrubber.
Avoid unsupported keywords like anyOf/oneOf/allOf, patternProperties, additionalProperties, minLength, maxLength, format, etc.
If you define custom tools, keep the top‑level schema as type: "object" with properties and simple enums.

See Tools and TypeBox schemas.

macOS Specific Issues

App Crashes when Granting Permissions (Speech/Mic)

If the app disappears or shows “Abort trap 6” when you click “Allow” on a privacy prompt: Fix 1: Reset TCC Cache

tccutil reset All com.equabot.mac.debug

Fix 2: Force New Bundle ID If resetting doesn’t work, change the BUNDLE_ID in scripts/package-mac-app.sh (e.g., add a .test suffix) and rebuild. This forces macOS to treat it as a new app.

Gateway stuck on “Starting…”

The app connects to a local gateway on port 18789. If it stays stuck: Fix 1: Stop the supervisor (preferred) If the gateway is supervised by launchd, killing the PID will just respawn it. Stop the supervisor first:

equabot gateway status
equabot gateway stop
# Or: launchctl bootout gui/$UID/com.equabot.gateway (replace with com.equabot.<profile> if needed)

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 equabot CLI is installed and matches the app version:

equabot --version
npm install -g equabot@<version>

Debug Mode

Get verbose logging:

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

Log Locations

Log	Location
Gateway file logs (structured)	`/tmp/equabot/equabot-YYYY-MM-DD.log` (or `logging.file`)
Gateway service logs (supervisor)	macOS: `$EQUABOT_STATE_DIR/logs/gateway.log` + `gateway.err.log` (default: `~/.equabot/logs/...`; profiles use `~/.equabot-<profile>/logs/...`) Linux: `journalctl --user -u equabot-gateway[-<profile>].service -n 200 --no-pager` Windows: `schtasks /Query /TN "Equabot Gateway (<profile>)" /V /FO LIST`
Session files	`$EQUABOT_STATE_DIR/agents/<agentId>/sessions/`
Media cache	`$EQUABOT_STATE_DIR/media/`
Credentials	`$EQUABOT_STATE_DIR/credentials/`

Health Check

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

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

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

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

Reset Everything

Nuclear option:

equabot gateway stop
# If you installed a service and want a clean install:
# equabot gateway uninstall

trash "${EQUABOT_STATE_DIR:-$HOME/.equabot}"
equabot channels login         # re-pair WhatsApp
equabot gateway restart           # or: equabot gateway

⚠️ This loses all sessions and requires re-pairing WhatsApp.

Getting Help

Check logs first: /tmp/equabot/ (default: equabot-YYYY-MM-DD.log, or your configured logging.file)
Search existing issues on GitHub
Open a new issue with:
- Equabot 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

Install & Updates

Gateway Operations

Web Interfaces

Platforms

macOS Companion App

​Troubleshooting 🔧

​Status & Diagnostics

​Common Issues

​No API key found for provider “anthropic”

​OAuth token refresh failed (Anthropic Claude subscription)

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

​CI Secrets Scan Failed

​Service Installed but Nothing is Running

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

​Service Environment (PATH + runtime)

​Skill missing API key in sandbox

​Service Running but Port Not Listening

​Unauthorized: Gateway Token Mismatch

​Address Already in Use (Port 18789)

​Extra Workspace Folders Detected

​Main chat running in a sandbox workspace

​”Agent was aborted”

​Agent failed before reply: Unknown model

​Messages Not Triggering

​Pairing Code Not Arriving

​Image + Mention Not Working

​Session Not Resuming

​Stale Session Errors (sessions.resolve)

​Agent Timing Out

​WhatsApp Disconnected

​Media Send Failing

​High Memory Usage

​Common troubleshooting

​“Gateway won’t start — configuration invalid”

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

​I’m running on my personal WhatsApp number — why is self-chat weird?

​WhatsApp logged me out. How do I re‑auth?

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

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

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

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

​Discord doesn’t reply in my server even with requireMention: false. Why?

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

​macOS Specific Issues

​App Crashes when Granting Permissions (Speech/Mic)

​Gateway stuck on “Starting…”

​Debug Mode

​Log Locations

​Health Check

​Reset Everything

​Getting Help

​Browser Not Starting (Linux)