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

# Gateway troubleshooting

# Gateway troubleshooting

This page is the deep runbook.
Start at [/help/troubleshooting](/datzi/help/troubleshooting) if you want the fast triage flow first.

## Command ladder

Run these first, in this order:

```bash theme={null}
datzi status
datzi gateway status
datzi logs --follow
datzi doctor
datzi channels status --probe
```

Expected healthy signals:

* `datzi gateway status` shows `Runtime: running` and `RPC probe: ok`.
* `datzi doctor` reports no blocking config/service issues.
* `datzi channels status --probe` shows connected/ready channels.

## No replies

If channels are up but nothing answers, check routing and policy before reconnecting anything.

```bash theme={null}
datzi status
datzi channels status --probe
datzi pairing list <channel>
datzi config get channels
datzi logs --follow
```

Look for:

* Pairing pending for DM senders.
* Group mention gating (`requireMention`, `mentionPatterns`).
* Channel/group allowlist mismatches.

Common signatures:

* `drop guild message (mention required` → group message ignored until mention.
* `pairing request` → sender needs approval.
* `blocked` / `allowlist` → sender/channel was filtered by policy.

Related:

* [/channels/troubleshooting](/datzi/channels/troubleshooting)
* [/channels/pairing](/datzi/channels/pairing)
* [/channels/groups](/datzi/channels/groups)

## Dashboard control ui connectivity

When dashboard/control UI will not connect, validate URL, auth mode, and secure context assumptions.

```bash theme={null}
datzi gateway status
datzi status
datzi logs --follow
datzi doctor
datzi gateway status --json
```

Look for:

* Correct probe URL and dashboard URL.
* Auth mode/token mismatch between client and gateway.
* HTTP usage where device identity is required.

Common signatures:

* `device identity required` → non-secure context or missing device auth.
* `unauthorized` / reconnect loop → token/password mismatch.
* `gateway connect failed:` → wrong host/port/url target.

Related:

* /web/control-ui
* [/gateway/authentication](/datzi/gateway/authentication)
* [/gateway/remote](/datzi/gateway/remote)

## Gateway service not running

Use this when service is installed but process does not stay up.

```bash theme={null}
datzi gateway status
datzi status
datzi logs --follow
datzi doctor
datzi gateway status --deep
```

Look for:

* `Runtime: stopped` with exit hints.
* Service config mismatch (`Config (cli)` vs `Config (service)`).
* Port/listener conflicts.

Common signatures:

* `Gateway start blocked: set gateway.mode=local` → local gateway mode is not enabled. Fix: set `gateway.mode="local"`in
  your config (or run `datzi configure`). If you are running Datzi via Podman using the dedicated `datzi` user,
  the config lives at `~datzi/.datzi/datzi.json`.
* `refusing to bind gateway ... without auth` → non-loopback bind without token/password.
* `another gateway instance is already listening` / `EADDRINUSE` → port conflict.

Related:

* /gateway/background-process
* [/gateway/configuration](/datzi/gateway/configuration)
* [/gateway/doctor](/datzi/gateway/troubleshooting)

## Channel connected messages not flowing

If channel state is connected but message flow is dead, focus on policy, permissions, and channel specific delivery
rules.

```bash theme={null}
datzi channels status --probe
datzi pairing list <channel>
datzi status --deep
datzi logs --follow
datzi config get channels
```

Look for:

* DM policy (`pairing`, `allowlist`, `open`, `disabled`).
* Group allowlist and mention requirements.
* Missing channel API permissions/scopes.

Common signatures:

* `mention required` → message ignored by group mention policy.
* `pairing` / pending approval traces → sender is not approved.
* `missing_scope`, `not_in_channel`, `Forbidden`, `401/403` → channel auth/permissions issue.

Related:

* [/channels/troubleshooting](/datzi/channels/troubleshooting)
* [/channels/whatsapp](/datzi/channels/whatsapp)
* [/channels/telegram](/datzi/channels/telegram)
* [/channels/discord](/datzi/channels/discord)

## Cron and heartbeat delivery

If cron or heartbeat did not run or did not deliver, verify scheduler state first, then delivery target.

```bash theme={null}
datzi cron status
datzi cron list
datzi cron runs --id <jobId> --limit 20
datzi system heartbeat last
datzi logs --follow
```

Look for:

* Cron enabled and next wake present.
* Job run history status (`ok`, `skipped`, `error`).
* Heartbeat skip reasons (`quiet-hours`, `requests-in-flight`, `alerts-disabled`).

Common signatures:

* `cron: scheduler disabled; jobs will not run automatically` → cron disabled.
* `cron: timer tick failed` → scheduler tick failed; check file/log/runtime errors.
* `heartbeat skipped` with `reason=quiet-hours` → outside active hours window.
* `heartbeat: unknown accountId` → invalid account id for heartbeat delivery target.

Related:

* [/automation/troubleshooting](/datzi/automation/troubleshooting)
* [/automation/cron-jobs](/datzi/automation/cron-jobs)
* [/gateway/heartbeat](/datzi/gateway/heartbeat)

## Node paired tool fails

If a node is paired but tools fail, isolate foreground, permission, and approval state.

```bash theme={null}
datzi nodes status
datzi nodes describe --node <idOrNameOrIp>
datzi approvals get --node <idOrNameOrIp>
datzi logs --follow
datzi status
```

Look for:

* Node online with expected capabilities.
* OS permission grants for camera/mic/location/screen.
* Exec approvals and allowlist state.

Common signatures:

* `NODE_BACKGROUND_UNAVAILABLE` → node app must be in foreground.
* `*_PERMISSION_REQUIRED` / `LOCATION_PERMISSION_REQUIRED` → missing OS permission.
* `SYSTEM_RUN_DENIED: approval required` → exec approval pending.
* `SYSTEM_RUN_DENIED: allowlist miss` → command blocked by allowlist.

Related:

* [/nodes/troubleshooting](/datzi/nodes/troubleshooting)
* [/nodes/index](/datzi/nodes/index)
* [/tools/exec](/datzi/tools/exec)

## Browser tool fails

Use this when browser tool actions fail even though the gateway itself is healthy.

```bash theme={null}
datzi browser status
datzi browser start --browser-profile datzi
datzi browser profiles
datzi logs --follow
datzi doctor
```

Look for:

* Valid browser executable path.
* CDP profile reachability.
* Extension relay tab attachment for `profile="chrome"`.

Common signatures:

* `Failed to start Chrome CDP on port` → browser process failed to launch.
* `browser.executablePath not found` → configured path is invalid.
* `Chrome extension relay is running, but no tab is connected` → extension relay not attached.
* `Browser attachOnly is enabled ... not reachable` → attach-only profile has no reachable target.

Related:

* [/tools/browser](/datzi/tools/browser)

## 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 theme={null}
datzi gateway status
datzi config get gateway.mode
datzi config get gateway.remote.url
datzi 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 theme={null}
datzi config get gateway.bind
datzi config get gateway.auth.token
datzi gateway status
datzi logs --follow
```

What to check:

* Non-loopback binds (`lan`, `tailnet`, `custom`) need auth configured.
* Old keys like `gateway.token` do not replace `gateway.auth.token`.

Common signatures:

* `refusing to bind gateway ... without auth` → bind+auth mismatch.
* `RPC probe: failed` while runtime is running → gateway alive but inaccessible with current auth/url.

### 3) Pairing and device identity state changed

```bash theme={null}
datzi devices list
datzi pairing list <channel>
datzi logs --follow
datzi 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:

```bash theme={null}
datzi gateway install --force
datzi gateway restart
```

Related:

* [/gateway/pairing](/datzi/channels/pairing)
* [/gateway/authentication](/datzi/gateway/authentication)
* /gateway/background-process