Gateway Pools: Troubleshooting

Troubleshooting

Failover Did Not Happen

# 1. Is the peer actually detected as down?
sqlite3 /data/gatecontrol.db "SELECT peer_id, alive, datetime(last_seen_at/1000,'unixepoch') FROM gateway_meta;"

# 2. If alive=1 but the peer is obviously offline:
#    Watchdog runs every 30s. Threshold defaults to 90s.
#    90+30 = max ~120s wait.

# 3. Check the routes table — should routes be pivoted?
sqlite3 /data/gatecontrol.db "SELECT id, domain, target_peer_id, original_peer_id FROM routes WHERE target_kind='gateway' AND enabled=1;"

# 4. Activity log
sqlite3 /data/gatecontrol.db "SELECT datetime(created_at/1000,'unixepoch'), event_type, message FROM activity_log WHERE event_type LIKE '%failover%' ORDER BY created_at DESC LIMIT 10;"

Routes Are Pivoted but the Frontend Returns 502/504

Possible causes:

Caddy reload failed — docker logs gatecontrol | grep -i caddy.*error
WG tunnel to failover member down — docker exec gatecontrol wg show and check handshake age

Failover companion does not know the route — hash mismatch:

# Server-expected hash for peer 84:
docker exec gatecontrol node -e "console.log(require('/app/src/services/gateways').computeConfigHash(84))"
# Hash reported by the companion:
sqlite3 /data/gatecontrol.db "SELECT last_config_hash FROM gateway_meta WHERE peer_id=84;"
# Manually trigger if there's a mismatch:
docker exec gatecontrol node -e "require('/app/src/services/gateways').notifyConfigChanged(84)"

Backend host unreachable from the failover member — from DS918: curl -v http://192.168.1.5:5001

LB Pool but All Requests Hit a Single Member

mode = 'load_balancing'? (not failover)
lb_policy set? (not NULL)
Are both members in gateway_meta.alive=1?
For ip_hash with a CDN in front: trusted_proxies only kicks in when the CDN IP falls into the configured ranges. CDN outside RFC1918? Add custom ranges via code patch in src/services/caddyConfig.js.
Caddy live config: docker exec gatecontrol curl -s http://127.0.0.1:2019/config/apps/http/servers/srv0/routes — verify upstreams has multiple entries.

Pool Won't Save — "members_array_required" / "duplicate_peer"

Frontend bug or race. Clear browser cache (Ctrl+Shift+R). DevTools Network: inspect the PUT request body — should be [{peer_id: <int>, priority: <int>}, …]. Duplicate peer_ids should not happen during normal UI flow (the dropdown filters them out).

Modal Says "No Members Yet" but the DB Has Some