Nanami DocsGuide
Search docsFilter pages by title

Common issues

Use this checklist when connectivity or enrollment does not behave as expected.

1) Node does not come online

Check:

  • node exists in the intended network,
  • WireGuard config was generated and applied correctly,
  • endpoint host can reach control plane and gateway path,
  • public key and interface config are not stale.

2) Gateway appears offline or unhealthy

Check:

  • join key scope/expiry (gateway_daemon vs gateway_manager),
  • NODE_JOIN_KEY consistency between manager and daemon,
  • heartbeat timestamps in Agents/Gateways pages,
  • host networking capabilities required for gateway runtime.

3) Policy changed but traffic did not

Check:

  • network routing mode (auto vs manual),
  • ingress/egress device IDs still valid in target network,
  • user/device preference overrides,
  • tunnel handshake recency and byte counters.
  • network runtime status endpoint (GET /api/v1/networks/:id/runtime-status) reports pending/applied/error.

Useful commands on gateway host:

bash
ip rule show
ip route show table 200
iptables -t mangle -S NANAMI_ROUTE_MARK

If running dry-run mode, verify logs include dry-run exec command traces.

4) DNS records changed but lookups do not update

Check:

  • DNS_RUNTIME_ENABLED is enabled on gateway-daemon deployment.
  • DNS_RUNTIME_BINARY exists in gateway-daemon runtime.
  • runtime files were rendered in DNS_RUNTIME_DIR.
  • network runtime status endpoint reports DNS running and no last error.

Useful commands on gateway host:

bash
ls -la /var/lib/nanami/gateway/dns
cat /var/lib/nanami/gateway/dns/Corefile
ps aux | grep coredns
dig @100.64.0.10 api.<zone> A

5) Authentication requests fail unexpectedly

Check:

  • token expiry and refresh behavior,
  • cookie/domain settings when using BFF,
  • reverse-proxy headers (x-forwarded-host, x-forwarded-proto),
  • clock drift on auth and gateway hosts.

6) Fast triage runbook

  1. Confirm control-plane health endpoint.
  2. Confirm gateway manager and gateway daemon heartbeat.
  3. Confirm node status and tunnel handshake timestamps.
  4. Confirm most recent policy/membership change.
  5. Roll back to last known-good state when needed.
Edit this page