Troubleshooting
zwallctl troubleshooting
Symptom → meaning
Scroll sideways to see the full table. Use the arrow keys when focused.
| Symptom | Meaning | Action |
|---|---|---|
connection refused to :8080 | default URL vs Manager 8443 | --manager-url https://HOST:8443 |
unknown command license / update | Community binary | use Enterprise zwallctl from the same release |
start / stop prints not implemented | remote start/stop not implemented | systemd |
restart 409 | Hosting Agent | systemd on the hosting unit; Hosting cannot receive restart |
unexpected response format on list | CLI expects data array; Manager may return agents/rules/logs | --output json or API |
| backup prints success, no dump file | API helper ≠ backup_db.sh | Backup |
Error: ... exit 1 | cobra exitWithError | read stderr; 401 → login |
map ls empty | wrong pin dir or no virt Agent | --pin-dir, root, /sys/fs/bpf |
secret-rotate flags jwt|db|all fail on Enterprise | different command | setup.sh --manager-secret-custody rotate |
log --follow not implemented | fact | poll zwallctl log |
| 409 cannot receive rules | Hosting observation | do not assign enforcement rules |
403 COMMUNITY_AGENT_LIMIT_REACHED | Community 3-Agent cap | delete unused Agents or use Enterprise |
| 403 license object | entitlement | Enterprise-only; see Enterprise edition |
| 2FA login via CLI fails | cobra login may not send two_factor_code | API login or disable 2FA in a break-glass process |