Skip to content
RemoteClaw

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:

Terminal window
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 → channels report connected or ready.
  • 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.

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 connected/ready 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.
- `AUTH_TOKEN_MISMATCH` with retry hints (`canRetryWithDeviceToken=true`) → one trusted device-token retry may occur automatically.
- 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` → gateway mode is unset/remote.
- `refusing to bind gateway ... without auth` → non-loopback bind without token/password.
- `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.
- `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/troubleshooting](/automation/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 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:


- `Failed to start Chrome CDP on port` → local browser launch failed.
- `browser.executablePath not found` → configured binary path is wrong.
- `No Chrome tabs found for profile="user"` → the Chrome MCP attach profile has no open local Chrome tabs.
- `Browser attachOnly is enabled ... not reachable` → attach-only profile has no live CDP target.


Deep pages:


- [/gateway/troubleshooting#browser-tool-fails](/gateway/troubleshooting#browser-tool-fails)
- [/tools/browser-linux-troubleshooting](/tools/browser-linux-troubleshooting)
- [/tools/browser-wsl2-windows-remote-cdp-troubleshooting](/tools/browser-wsl2-windows-remote-cdp-troubleshooting)