Skip to main content

​
Gateway troubleshooting

This page is the deep runbook. Start at /help/troubleshooting if you want the fast triage flow first.

​
Command ladder

Run these first, in this order: 
fased status
fased gateway status
fased logs --follow
fased doctor
fased channels status --probe
Expected healthy signals:
  • fased gateway status shows Runtime: running and RPC probe: ok.
  • fased doctor reports no blocking config/service issues.
  • fased channels status --probe shows connected/ready channels.

​
No replies

If channels are up but nothing answers, check routing and policy before reconnecting anything. 
fased status
fased channels status --probe
fased pairing list --channel <channel> [--account <id>]
fased config get channels
fased 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:

​
Dashboard and Control UI connectivity

When dashboard/control UI will not connect, validate URL, auth mode, and secure context assumptions. 
fased gateway status
fased status
fased logs --follow
fased doctor
fased 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.
  • device nonce required / device nonce mismatch → client is not completing the challenge-based device auth flow (connect.challenge + device.nonce).
  • device signature invalid / device signature expired → client signed the wrong payload (or stale timestamp) for the current handshake.
  • unauthorized / reconnect loop → token/password mismatch.
  • gateway connect failed: → wrong host/port/url target.
Device auth v2 migration check: 
fased --version
fased doctor
fased gateway status
If logs show nonce/signature errors, update the connecting client and verify it:
  1. waits for connect.challenge
  2. signs the challenge-bound payload
  3. sends connect.params.device.nonce with the same challenge nonce
Related:

​
Gateway service not running

Use this when service is installed but process does not stay up. 
fased gateway status
fased status
fased logs --follow
fased doctor
fased 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 fased configure). If you are running Fased via Podman using the dedicated fased user, the config lives at ~fased/.fased/fased.json.
  • refusing to bind gateway ... without auth → non-loopback bind without token/password.
  • another gateway instance is already listening / EADDRINUSE → port conflict.
Related:

​
Channel connected messages not flowing

If channel state is connected but message flow is dead, focus on policy, permissions, and channel specific delivery rules. 
fased channels status --probe
fased pairing list --channel <channel> [--account <id>]
fased status --deep
fased logs --follow
fased 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:

​
Tasks and heartbeat delivery

If a scheduled task or heartbeat did not run or did not deliver, verify scheduler state first, then delivery target. 
fased task status
fased task list
fased task runs --id <jobId> --limit 20
fased system heartbeat last
fased logs --follow
Look for:
  • Scheduler enabled and next wake present.
  • Task activity 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.
  • heartbeat skipped with reason=dm-blocked → heartbeat target resolved to a DM-style destination while agents.defaults.heartbeat.directPolicy (or per-agent override) is set to block.
Related:

​
Node paired tool fails

If a node is paired but tools fail, isolate foreground, permission, and approval state. 
fased nodes status
fased nodes describe --node <idOrNameOrIp>
fased approvals get --node <idOrNameOrIp>
fased logs --follow
fased 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:

​
Browser tool fails

Use this when browser tool actions fail even though the gateway itself is healthy. 
fased browser status
fased browser start --browser-profile fased
fased browser profiles
fased logs --follow
fased 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:

​
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

fased gateway status
fased config get gateway.mode
fased config get gateway.remote.url
fased 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

fased config get gateway.bind
fased config get gateway.auth.token
fased gateway status
fased 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

fased devices list
fased pairing list --channel <channel> [--account <id>]
fased logs --follow
fased 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: 
fased gateway install --force
fased gateway restart
Related: