Troubleshooting

Common issues, debug logging, agent connectivity, and database migration troubleshooting.

Dashboard won't load

• Check the service is running: systemctl --user status noba-web.service
• Check the port: curl http://localhost:8080/api/health
• Check logs: journalctl --user -u noba-web.service -n 50
• Check for port conflicts: lsof -i :8080

Login issues

• Rate limiting: After 5 failed attempts in 5 minutes, the IP is locked for 30 minutes. Reset with journalctl --user -u noba-web.service | grep "rate limit"
• Clock sync: TOTP requires NTP-synced clocks. Check with timedatectl
• Admin password reset: noba admin-reset <username>

Stats show "Offline"

• Check agent connectivity: journalctl --user -u noba-web.service | grep agent
• Check agent logs on the remote host
• Verify WebSocket connectivity between agent and server

Integration cards showing errors

• Pi-hole: v6 uses session auth — enter password, not API token. Check Settings → Integrations → Pi-hole
• TrueNAS: Verify API key has correct permissions. Test connection from the UI
• Proxmox: If using API tokens, ensure token name format is user@realm!tokenname
• qBittorrent: v5.0+ requires specific cookie handling — ensure you're on the latest NOBA version

Agent commands stuck in "queued"

• Check agent capability registry version mismatch — agents report their supported commands on connect
• Verify the agent process is running on the remote host
• Check WebSocket connectivity: journalctl --user -u noba-agent.service

Backup failures

• Verify the backup destination is accessible and has sufficient space
• Check Settings → Backup for the last error message
• For database backups, verify the appropriate tool is installed (pg_dump for PostgreSQL, mysqldump for MySQL)

Docker-specific issues

• Proxmox AppArmor: Docker on Proxmox may need AppArmor profile adjustments for container monitoring
• Self-update: Docker containers use image tags — pin to a specific version in docker-compose.yml
• Volume permissions: Ensure ./data/config and ./data/db are writable by the container user

Stale UI after update

Clear browser cache or do a hard refresh (Ctrl+Shift+R). The frontend build includes cache-busting hashes, but browsers may cache the service worker.

Reset to defaults

Stop NOBA, delete ~/.config/noba-web/, delete ~/.local/share/noba-history.db, and restart. This resets all settings, users, and metrics.