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 1,000-session free-tier cap Activate a capacity licence — see Licensing

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

Licensing page shows EXPIRED and the cap dropped back to 1,000

Seen on the evaluation appliance after it has been running a while, or after a
power cycle. Re-submit the same licence file on the Licensing page — it returns
to VALID with the full capacity straight away, and nothing else is disturbed.

Check what the box actually thinks:

quantum-license-status

EXPIRED and NOT_ACTIVATED mean different things here, and the difference
tells you where to look:

State Meaning
NOT_ACTIVATED No licence has been installed, or the sealed material could not be read back
VALID / GRACE Licensed; capacity granted
EXPIRED The licence was read back successfully, but the validity window computed as elapsed
TAMPER The TPM clock has moved backwards relative to activation

EXPIRED therefore does not indicate a damaged licence or a changed machine
identity — the fingerprint and the sealed material are both intact, which is why
re-submitting the same file works.

Nothing stops while this is the case. Licence enforcement is capacity-only: no
feature is gated on holding a licence, only quantity is. The box keeps
configuring, onboarding, forwarding, shaping and accounting normally at up to
1,000 sessions. You do not need a licence to evaluate the appliance at all —
the free tier needs neither a licence nor a TPM.

Tracked as bng#52.