Troubleshooting

Header shows `VPP ?` for > 10s

The controller can't talk to vpp-bridge. Usually a punt-socket or vpp-bridge health issue:

sudo systemctl status vpp vpp-bridge quantum-controller
sudo vppctl show errors | grep -i punt      # if "Socket TX" errors, vpp-bridge lost the socket

Restart in the right order (vpp first, then vpp-bridge, then controller):

sudo systemctl restart vpp
sleep 3
sudo systemctl restart vpp-bridge
sleep 2
sudo systemctl restart quantum-controller

DHCP DISCOVERs are being dropped

Controller journal will tell you why:

sudo journalctl -u quantum-controller --since '5 minutes ago' | grep onDiscover

Common causes:

Message	Cause	Fix
`captive required but no captive portal IP configured, dropping`	Gated AAA + no `portal_ip` set	Portal Config → set portal_ip
`pool 'default' exhausted`	DHCP pool full	Pools & DNS → add capacity
`unknown line identity, unknown=reject`	Gated AAA, unlisted line, policy set to reject	Provision the line or flip `unknown` to `captive`
`session cap reached`	1000-session Community Edition cap	Contact BlueDot for a larger license

Sessions header shows N but Sessions page table is empty

The header polls one endpoint; the page polls a different one. Usually a transient auth race just after login — hard-refresh the page (Cmd+Shift+R / Ctrl+Shift+R). If it persists across refreshes, check that the session cookie is still valid: User menu (top-right) → Profile → Session info.

CPESIM demo won't start — `pool gateway 10.50.0.1/24 is already held by host-demo0p`

The controller has a stale access_interfaces binding from a previous CPESIM run that didn't teardown cleanly. Reset:

sudo /usr/local/bin/reset-cpesim

This clears the stale record + restarts the whole CPESIM engine in the right order (vpp → vpp-bridge → controller → bng-demo).

`AAA (LOCAL) DOWN — provider unreachable` on the dashboard

The AAA local-provider file isn't readable. Usually a permissions issue after a manual API key mint:

sudo ls -la /var/lib/quantum-controller/api_keys.json
# should be owned by quantum-controller:quantum-controller, mode 0600
sudo chown quantum-controller:quantum-controller /var/lib/quantum-controller/api_keys.json
sudo systemctl restart quantum-controller

Long-running API calls (e.g., snapshot restore) return HTTP 500

Gunicorn's per-worker timeout killed the request. The installer drops in a 180s override at /etc/systemd/system/bng-deploy.service.d/10-timeout.conf — check it's still there. If you're doing something that takes longer than 180s (e.g., importing 5000 subscribers), bump the override:

sudo sed -i 's/--timeout 180/--timeout 300/' /etc/systemd/system/bng-deploy.service.d/10-timeout.conf
sudo systemctl daemon-reload
sudo systemctl restart bng-deploy