Skip to main content

Troubleshooting

Start at the boundary closest to the failure: process startup, local HTTP access, browser-to-API access, then agent connectivity.

The UI loads but API calls fail​

  • Confirm the server is listening on the address in app-server/config.yml.
  • Check VITE_API_BASE_URL and the Vite development proxy target.
  • Inspect the browser network panel for the actual request URL and response.
  • When using separate origins, verify the server's allowed-origin configuration.

Initial setup is unavailable​

Bootstrap requires both an empty user database and a non-empty bootstrap-token. Restart the server after changing configuration. Once a root user exists, bootstrap is intentionally unavailable.

An agent does not connect​

  • Confirm the WebSocket scheme, host, port, and /ws/agent path.
  • Verify the agent identity and token match the server record.
  • Check DNS, firewall, proxy WebSocket support, and TLS trust from the agent host.
  • Read both server and agent logs around the same timestamp.

A scan module fails​

Network modules may require operating-system capabilities or external programs. Confirm the module is enabled, its target is valid, and its dependency is installed. Nmap enrichment requires an nmap binary. Some ICMP and packet-capture operations require additional permissions depending on the host.

The server database grows unexpectedly​

From app-server, inspect SQLite usage:

../.venv/bin/python cli.py db usage --config config.yml

Add --json for machine-readable output. The admin UI also exposes database usage under Admin → Database Usage.

Last updated on