> ## Documentation Index
> Fetch the complete documentation index at: https://agdiai-597e782f.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

# 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:

```bash theme={"theme":{"light":"min-light","dark":"min-dark"}}
agdi status
agdi status --all
agdi gateway probe
agdi gateway status
agdi doctor
agdi channels status --probe
agdi logs --follow
```

Good output in one line:

* `agdi status` → shows configured channels and no obvious auth errors.
* `agdi status --all` → full report is present and shareable.
* `agdi gateway probe` → expected gateway target is reachable (`Reachable: yes`). `RPC: limited - missing scope: operator.read` is degraded diagnostics, not a connect failure.
* `agdi gateway status` → `Runtime: running` and `RPC probe: ok`.
* `agdi doctor` → no blocking config/service errors.
* `agdi channels status --probe` → channels report `connected` or `ready`.
* `agdi 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](https://agdiai-597e782f.mintlify.site/gateway/troubleshooting.md#anthropic-429-extra-usage-required-for-long-context).

## Plugin install fails with missing agdi extensions

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

Fix in the plugin package:

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

Example:

```json theme={"theme":{"light":"min-light","dark":"min-dark"}}
{
  "name": "@openclaw/my-plugin",
  "version": "1.2.3",
  "agdi": {
    "extensions": ["./dist/index.js"]
  }
}
```

Reference: [Plugin architecture](https://agdiai-597e782f.mintlify.site/plugins/architecture.md)

## Decision tree

```mermaid theme={"theme":{"light":"min-light","dark":"min-dark"}}
flowchart TD
  A[Agdi 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/]
```

> [accordion] No replies
>
> ```bash theme={"theme":{"light":"min-light","dark":"min-dark"}}
> agdi status
> agdi gateway status
> agdi channels status --probe
> agdi pairing list --channel <channel> [--account <id>]
> agdi 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](https://agdiai-597e782f.mintlify.site/gateway/troubleshooting.md#no-replies)
> * [/channels/troubleshooting](https://agdiai-597e782f.mintlify.site/channels/troubleshooting.md)
> * [/channels/pairing](https://agdiai-597e782f.mintlify.site/channels/pairing.md)

> [accordion] Dashboard or Control UI will not connect
>
> ```bash theme={"theme":{"light":"min-light","dark":"min-dark"}}
> agdi status
> agdi gateway status
> agdi logs --follow
> agdi doctor
> agdi channels status --probe
> ```
>
> Good output looks like:
>
> * `Dashboard: http://...` is shown in `agdi 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](https://agdiai-597e782f.mintlify.site/gateway/troubleshooting.md#dashboard-control-ui-connectivity)
> * [/web/control-ui](https://agdiai-597e782f.mintlify.site/web/control-ui.md)
> * [/gateway/authentication](https://agdiai-597e782f.mintlify.site/gateway/authentication.md)

> [accordion] Gateway will not start or service installed but not running
>
> ```bash theme={"theme":{"light":"min-light","dark":"min-dark"}}
> agdi status
> agdi gateway status
> agdi logs --follow
> agdi doctor
> agdi 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](https://agdiai-597e782f.mintlify.site/gateway/troubleshooting.md#gateway-service-not-running)
> * [/gateway/background-process](https://agdiai-597e782f.mintlify.site/gateway/background-process.md)
> * [/gateway/configuration](https://agdiai-597e782f.mintlify.site/gateway/configuration.md)

> [accordion] Channel connects but messages do not flow
>
> ```bash theme={"theme":{"light":"min-light","dark":"min-dark"}}
> agdi status
> agdi gateway status
> agdi logs --follow
> agdi doctor
> agdi 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](https://agdiai-597e782f.mintlify.site/gateway/troubleshooting.md#channel-connected-messages-not-flowing)
> * [/channels/troubleshooting](https://agdiai-597e782f.mintlify.site/channels/troubleshooting.md)

> [accordion] Cron or heartbeat did not fire or did not deliver
>
> ```bash theme={"theme":{"light":"min-light","dark":"min-dark"}}
> agdi status
> agdi gateway status
> agdi cron status
> agdi cron list
> agdi cron runs --id <jobId> --limit 20
> agdi 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](https://agdiai-597e782f.mintlify.site/gateway/troubleshooting.md#cron-and-heartbeat-delivery)
> * [/automation/troubleshooting](https://agdiai-597e782f.mintlify.site/automation/troubleshooting.md)
> * [/gateway/heartbeat](https://agdiai-597e782f.mintlify.site/gateway/heartbeat.md)

> [accordion] Node is paired but tool fails camera canvas screen exec
>
> ```bash theme={"theme":{"light":"min-light","dark":"min-dark"}}
> agdi status
> agdi gateway status
> agdi nodes status
> agdi nodes describe --node <idOrNameOrIp>
> agdi 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](https://agdiai-597e782f.mintlify.site/gateway/troubleshooting.md#node-paired-tool-fails)
> * [/nodes/troubleshooting](https://agdiai-597e782f.mintlify.site/nodes/troubleshooting.md)
> * [/tools/exec-approvals](https://agdiai-597e782f.mintlify.site/tools/exec-approvals.md)

> [accordion] Browser tool fails
>
> ```bash theme={"theme":{"light":"min-light","dark":"min-dark"}}
> agdi status
> agdi gateway status
> agdi browser status
> agdi logs --follow
> agdi doctor
> ```
>
> Good output looks like:
>
> * Browser status shows `running: true` and a chosen browser/profile.
> * `agdi` 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](https://agdiai-597e782f.mintlify.site/gateway/troubleshooting.md#browser-tool-fails)
> * [/tools/browser-linux-troubleshooting](https://agdiai-597e782f.mintlify.site/tools/browser-linux-troubleshooting.md)
> * [/tools/browser-wsl2-windows-remote-cdp-troubleshooting](https://agdiai-597e782f.mintlify.site/tools/browser-wsl2-windows-remote-cdp-troubleshooting.md)


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.