This is the deep runbook. Start at /help/troubleshooting for the fast triage flow first.

Command ladder

Run in this order:

apus status
apus gateway status
apus logs --follow
apus doctor
apus channels status --probe

Healthy signals:

Symptom index

This page is an index. The runbook sections are documented on six pages, grouped by symptom area. Open the page that matches what you are seeing.

Page Read it when
Updates and rollbacks An update, downgrade, or split-brain install left the Gateway down or mismatched.
Skills and model providers A skill root is skipped, or provider calls fail with 429, 403, or silent agent-run errors.
Agent replies and Control UI A run fails with a storage error, no reply arrives, or the Control UI will not connect.
Gateway service and process The service will not run or stay up, macOS supervision misbehaves, or memory forces an exit.
Config validation and checks The Gateway rejected a config, or check warnings appear in status and doctor output.
Channel delivery and tools A channel connects but does not deliver, or a node or browser tool call fails.

Where each section moved

Every anchor this page used to publish is kept here, so an existing link such as /gateway/troubleshooting#gateway-rejected-invalid-config still resolves. Each entry points at the page that now holds the content.

If you upgraded and something suddenly broke

Most post-upgrade breakage is config drift or stricter defaults now being enforced.

1. Auth and URL override behavior changed 
```bash
apus gateway status
apus config get gateway.mode
apus config get gateway.remote.url
apus config get gateway.auth.mode
```

What to check:

- If `gateway.mode=remote`, CLI calls may be targeting remote while your local service is fine.
- Explicit `--url` calls do not fall back to stored credentials.

Common signatures:

- `gateway connect failed:` → wrong URL target.
- `unauthorized` → endpoint reachable but wrong auth.
2. Bind and auth guardrails are stricter 
```bash
apus config get gateway.bind
apus config get gateway.auth.mode
apus config get gateway.auth.token
apus gateway status
apus logs --follow
```

What to check:

- Non-loopback binds (`lan`, `tailnet`, `custom`) need a valid gateway auth path: shared token/password auth, or a correctly configured non-loopback `trusted-proxy` deployment.
- Old keys like `gateway.token` do not replace `gateway.auth.token`.

Common signatures:

- `refusing to bind gateway ... without auth` → non-loopback bind without a valid gateway auth path.
- a failed connectivity check while runtime is running → gateway alive but inaccessible with current auth/url.
3. Pairing and device identity state changed 
```bash
apus devices list
apus pairing list --channel <channel> [--account <id>]
apus logs --follow
apus doctor
```

What to check:

- Pending device approvals for dashboard/nodes.
- Pending DM pairing approvals after policy or identity changes.

Common signatures:

- `device identity required` → device auth not satisfied.
- `pairing required` → sender/device must be approved.

If the service config and runtime still disagree after checks, reinstall service metadata from the same profile/state directory:

apus gateway install --force
apus gateway restart

Related:

Related