General Troubleshooting

Troubleshooting

If you only have 2 minutes, use this page as a triage front door.

First 60 seconds

Run this exact ladder in order:

remoteclaw status
remoteclaw status --all
remoteclaw gateway probe
remoteclaw gateway status
remoteclaw doctor
remoteclaw channels status --probe
remoteclaw logs --follow

Good output in one line:

• remoteclaw status → shows configured channels and no obvious auth errors.
• remoteclaw status --all → full report is present and shareable.
• remoteclaw gateway probe → expected gateway target is reachable (Reachable: yes). RPC: limited - missing scope: operator.read is degraded diagnostics, not a connect failure.
• remoteclaw gateway status → Runtime: running and RPC probe: ok.
• remoteclaw doctor → no blocking config/service errors.
• remoteclaw channels status --probe → reachable gateway returns live per-account transport state plus probe/audit results such as works or audit ok; if the gateway is unreachable, the command falls back to config-only summaries.
• remoteclaw logs --follow → steady activity, no repeating fatal errors.

Anthropic long context 429

If you see: HTTP 429: rate_limit_error: Extra usage is required for long context requests, go to /gateway/troubleshooting#anthropic-429-extra-usage-required-for-long-context.

Local OpenAI-compatible backend works directly but fails in RemoteClaw

If your local or self-hosted /v1 backend answers small direct /v1/chat/completions probes but fails on remoteclaw infer model run or normal agent turns:

1. If the error mentions messages[].content expecting a string, set models.providers.<provider>.models[].compat.requiresStringContent: true.
2. If the backend still fails only on RemoteClaw agent turns, set models.providers.<provider>.models[].compat.supportsTools: false and retry.
3. If tiny direct calls still work but larger RemoteClaw prompts crash the backend, treat the remaining issue as an upstream model/server limitation and continue in the deep runbook: /gateway/troubleshooting#local-openai-compatible-backend-passes-direct-probes-but-agent-runs-fail

Plugin install fails with missing remoteclaw extensions

If install fails with package.json missing remoteclaw.extensions, the plugin package is using an old shape that RemoteClaw no longer accepts.

Fix in the plugin package:

1. Add remoteclaw.extensions to package.json.
2. Point entries at built runtime files (usually ./dist/index.js).
3. Republish the plugin and run remoteclaw plugins install <package> again.

Example:

{
  "name": "@remoteclaw/my-plugin",
  "version": "1.2.3",
  "remoteclaw": {
    "extensions": ["./dist/index.js"]
  }
}

Reference: Plugin architecture

Decision tree

flowchart TD
  A[RemoteClaw is not working] --> B{What breaks first}
  B --> C[No replies]
  B --> D[Dashboard or Control UI will not connect]
  B --> E[Gateway will not start or service not running]
  B --> F[Channel connects but messages do not flow]
  B --> G[Cron or heartbeat did not fire or did not deliver]
  B --> H[Node is paired but camera canvas screen exec fails]
  B --> I[Browser tool fails]

  C --> C1[/No replies section/]
  D --> D1[/Control UI section/]
  E --> E1[/Gateway section/]
  F --> F1[/Channel flow section/]
  G --> G1[/Automation section/]
  H --> H1[/Node tools section/]
  I --> I1[/Browser section/]

```bash remoteclaw status remoteclaw gateway status remoteclaw channels status --probe remoteclaw pairing list --channel [--account ] remoteclaw logs --follow ```

Good output looks like:

- `Runtime: running`
- `RPC probe: ok`
- Your channel shows transport connected and, where supported, `works` or `audit ok` in `channels status --probe`
- Sender appears approved (or DM policy is open/allowlist)

Common log signatures:

- `drop guild message (mention required` → mention gating blocked the message in Discord.
- `pairing request` → sender is unapproved and waiting for DM pairing approval.
- `blocked` / `allowlist` in channel logs → sender, room, or group is filtered.

Deep pages:

- [/gateway/troubleshooting#no-replies](/gateway/troubleshooting#no-replies)
- [/channels/troubleshooting](/channels/troubleshooting)
- [/channels/pairing](/channels/pairing)

```bash remoteclaw status remoteclaw gateway status remoteclaw logs --follow remoteclaw doctor remoteclaw channels status --probe ```

Good output looks like:

- `Dashboard: http://...` is shown in `remoteclaw gateway status`
- `RPC probe: ok`
- No auth loop in logs

Common log signatures:

- `device identity required` → HTTP/non-secure context cannot complete device auth.
- `origin not allowed` → browser `Origin` is not allowed for the Control UI
  gateway target.
- `AUTH_TOKEN_MISMATCH` with retry hints (`canRetryWithDeviceToken=true`) → one trusted device-token retry may occur automatically.
- That cached-token retry reuses the cached scope set stored with the paired
  device token. Explicit `deviceToken` / explicit `scopes` callers keep
  their requested scope set instead.
- On the async Tailscale Serve Control UI path, failed attempts for the same
  `{scope, ip}` are serialized before the limiter records the failure, so a
  second concurrent bad retry can already show `retry later`.
- `too many failed authentication attempts (retry later)` from a localhost
  browser origin → repeated failures from that same `Origin` are temporarily
  locked out; another localhost origin uses a separate bucket.
- repeated `unauthorized` after that retry → wrong token/password, auth mode mismatch, or stale paired device token.
- `gateway connect failed:` → UI is targeting the wrong URL/port or unreachable gateway.

Deep pages:

- [/gateway/troubleshooting#dashboard-control-ui-connectivity](/gateway/troubleshooting#dashboard-control-ui-connectivity)
- [/web/control-ui](/web/control-ui)
- [/gateway/authentication](/gateway/authentication)

```bash remoteclaw status remoteclaw gateway status remoteclaw logs --follow remoteclaw doctor remoteclaw channels status --probe ```

Good output looks like:

- `Service: ... (loaded)`
- `Runtime: running`
- `RPC probe: ok`

Common log signatures:

- `Gateway start blocked: set gateway.mode=local` or `existing config is missing gateway.mode` → gateway mode is remote, or the config file is missing the local-mode stamp and should be repaired.
- `refusing to bind gateway ... without auth` → non-loopback bind without a valid gateway auth path (token/password, or trusted-proxy where configured).
- `another gateway instance is already listening` or `EADDRINUSE` → port already taken.

Deep pages:

- [/gateway/troubleshooting#gateway-service-not-running](/gateway/troubleshooting#gateway-service-not-running)
- [/gateway/background-process](/gateway/background-process)
- [/gateway/configuration](/gateway/configuration)

```bash remoteclaw status remoteclaw gateway status remoteclaw logs --follow remoteclaw doctor remoteclaw channels status --probe ```

Good output looks like:

- Channel transport is connected.
- Pairing/allowlist checks pass.
- Mentions are detected where required.

Common log signatures:

- `mention required` → group mention gating blocked processing.
- `pairing` / `pending` → DM sender is not approved yet.
- `not_in_channel`, `missing_scope`, `Forbidden`, `401/403` → channel permission token issue.

Deep pages:

- [/gateway/troubleshooting#channel-connected-messages-not-flowing](/gateway/troubleshooting#channel-connected-messages-not-flowing)
- [/channels/troubleshooting](/channels/troubleshooting)

```bash remoteclaw status remoteclaw gateway status remoteclaw cron status remoteclaw cron list remoteclaw cron runs --id --limit 20 remoteclaw logs --follow ```

Good output looks like:

- `cron.status` shows enabled with a next wake.
- `cron runs` shows recent `ok` entries.
- Heartbeat is enabled and not outside active hours.

Common log signatures:

• cron: scheduler disabled; jobs will not run automatically → cron is disabled.

• heartbeat skipped with reason=quiet-hours → outside configured active hours.

• heartbeat skipped with reason=empty-heartbeat-file → HEARTBEAT.md exists but only contains blank/header-only scaffolding.

• heartbeat skipped with reason=no-tasks-due → HEARTBEAT.md task mode is active but none of the task intervals are due yet.

• heartbeat skipped with reason=alerts-disabled → all heartbeat visibility is disabled (showOk, showAlerts, and useIndicator are all off).

• requests-in-flight → main lane busy; heartbeat wake was deferred. - unknown accountId → heartbeat delivery target account does not exist.

  Deep pages:
  
  - [/gateway/troubleshooting#cron-and-heartbeat-delivery](/gateway/troubleshooting#cron-and-heartbeat-delivery)
  - [/automation/cron-jobs#troubleshooting](/automation/cron-jobs#troubleshooting)
  - [/gateway/heartbeat](/gateway/heartbeat)

  ```bash remoteclaw status remoteclaw gateway status remoteclaw nodes status remoteclaw nodes describe --node remoteclaw logs --follow ```

  Good output looks like:
  
  - Node is listed as connected and paired for role `node`.
  - Capability exists for the command you are invoking.
  - Permission state is granted for the tool.
  
  Common log signatures:
  
  - `NODE_BACKGROUND_UNAVAILABLE` → bring node app to foreground.
  - `*_PERMISSION_REQUIRED` → OS permission was denied/missing.
  - `SYSTEM_RUN_DENIED: approval required` → exec approval is pending.
  - `SYSTEM_RUN_DENIED: allowlist miss` → command not on exec allowlist.
  
  Deep pages:
  
  - [/gateway/troubleshooting#node-paired-tool-fails](/gateway/troubleshooting#node-paired-tool-fails)
  - [/nodes/troubleshooting](/nodes/troubleshooting)
  - [/tools/exec-approvals](/tools/exec-approvals)

  ```bash remoteclaw config get tools.exec.host remoteclaw config get tools.exec.security remoteclaw config get tools.exec.ask remoteclaw gateway restart ```

  What changed:
  
  - If `tools.exec.host` is unset, the default is `auto`.
  - `host=auto` resolves to `sandbox` when a sandbox runtime is active, `gateway` otherwise.
  - `host=auto` is routing only; the no-prompt "YOLO" behavior comes from `security=full` plus `ask=off` on gateway/node.
  - On `gateway` and `node`, unset `tools.exec.security` defaults to `full`.
  - Unset `tools.exec.ask` defaults to `off`.
  - Result: if you are seeing approvals, some host-local or per-session policy tightened exec away from the current defaults.
  
  Restore current default no-approval behavior:
  
  ```bash
  remoteclaw config set tools.exec.host gateway
  remoteclaw config set tools.exec.security full
  remoteclaw config set tools.exec.ask off
  remoteclaw gateway restart
  ```
  
  Safer alternatives:
  
  - Set only `tools.exec.host=gateway` if you just want stable host routing.
  - Use `security=allowlist` with `ask=on-miss` if you want host exec but still want review on allowlist misses.
  - Enable sandbox mode if you want `host=auto` to resolve back to `sandbox`.
  
  Common log signatures:
  
  - `Approval required.` → command is waiting on `/approve ...`.
  - `SYSTEM_RUN_DENIED: approval required` → node-host exec approval is pending.
  - `exec host=sandbox requires a sandbox runtime for this session` → implicit/explicit sandbox selection but sandbox mode is off.
  
  Deep pages:
  
  - [/tools/exec](/tools/exec)
  - [/tools/exec-approvals](/tools/exec-approvals)
  - [/gateway/security#runtime-expectation-drift](/gateway/security#runtime-expectation-drift)

  ```bash remoteclaw status remoteclaw gateway status remoteclaw browser status remoteclaw logs --follow remoteclaw doctor ```

  Good output looks like:
  
  - Browser status shows `running: true` and a chosen browser/profile.
  - `remoteclaw` starts, or `user` can see local Chrome tabs.
  
  Common log signatures:
  
  - `unknown command "browser"` or `unknown command 'browser'` → `plugins.allow` is set and does not include `browser`.
  - `Failed to start Chrome CDP on port` → local browser launch failed.
  - `browser.executablePath not found` → configured binary path is wrong.
  - `browser.cdpUrl must be http(s) or ws(s)` → the configured CDP URL uses an unsupported scheme.
  - `browser.cdpUrl has invalid port` → the configured CDP URL has a bad or out-of-range port.
  - `No Chrome tabs found for profile="user"` → the Chrome MCP attach profile has no open local Chrome tabs.
  - `Remote CDP for profile "<name>" is not reachable` → the configured remote CDP endpoint is not reachable from this host.
  - `Browser attachOnly is enabled ... not reachable` or `Browser attachOnly is enabled and CDP websocket ... is not reachable` → attach-only profile has no live CDP target.
  - stale viewport / dark-mode / locale / offline overrides on attach-only or remote CDP profiles → run `remoteclaw browser stop --browser-profile <name>` to close the active control session and release emulation state without restarting the gateway.
  
  Deep pages:
  
  - [/gateway/troubleshooting#browser-tool-fails](/gateway/troubleshooting#browser-tool-fails)
  - [/tools/browser#missing-browser-command-or-tool](/tools/browser#missing-browser-command-or-tool)
  - [/tools/browser-linux-troubleshooting](/tools/browser-linux-troubleshooting)
  - [/tools/browser-wsl2-windows-remote-cdp-troubleshooting](/tools/browser-wsl2-windows-remote-cdp-troubleshooting)

Related

• FAQ — frequently asked questions
• Gateway Troubleshooting — gateway-specific issues
• Doctor — automated health checks and repairs
• Channel Troubleshooting — channel connectivity issues
• Automation Troubleshooting — cron and heartbeat issues