Troubleshooting¶

Agent installation fails¶

The problem: You ran the install command but the output shows an error, or the command exits without completing.

Verify internet access: ping -c 3 qbee.io (expected: three replies).
Verify script URL reachable: wget -qO /dev/null https://setup.qbee.io && echo "OK" (expected: prints "OK").
Verify sudo: sudo whoami (expected: prints "root").
If behind a proxy, see proxy settings for environment configuration.

The problem: The install command runs but reports "invalid bootstrap key" or "key not found."

Verify the key was copied in full. It should be a long alphanumeric string with no spaces.
Check in the Qbee console that the key has not been deleted (click your display name → Bootstrap keys).

The problem: The agent installed without errors, but the device appears Offline in the console (or does not appear at all).

Verify agent running: ps aux | grep qbee-agent (expected: a process listed).
Verify connectivity: ping -c 3 qbee.io (expected: three replies).
Check logs: sudo journalctl -u qbee-agent --since "5 min ago" | tail -5 (expected: no connection errors or TLS failures).

The problem: You committed a configuration change, but the device has not converged after 5 minutes.

Verify agent running: ps aux | grep qbee-agent (expected: a process listed).
Check the commit appears in the audit log (Monitor → Audit log in the Qbee console).
Check logs: sudo journalctl -u qbee-agent --since "10 min ago" | grep -i "error" (expected: no output, meaning no errors).

The problem: The configuration was committed and the audit log shows success, but the user does not exist on the device.

Verify the configuration was committed (not just saved) in the Qbee console.
Check agent ran since commit: sudo journalctl -u qbee-agent --since "5 min ago" (expected: log entries showing the agent ran a configuration cycle).
Verify manually: getent passwd demo (expected: a line containing "demo").