← Back to Documentation

Troubleshooting

Solutions for common issues with VigilPrism server, agents, and scanning operations.

Jump to Section

Agent IssuesDashboard IssuesDatabase IssuesScanning IssuesNetwork IssuesLog Locations

Agent Issues

Agent not connecting to server

Symptoms:

  • Agent shows 'Disconnected' or 'Offline' status
  • No heartbeat received on server
  • Agent logs show connection timeout errors

Solutions:

  • →Verify the server URL is correct in agent configuration (check for typos, correct port)
  • →Ensure the server is running and accessible from the agent host
  • →Check firewall rules allow outbound connections on port 8000 (or your configured port)
  • →Verify the enrollment token hasn't expired
  • →Test connectivity: curl http://your-server:8000/api/v1/health
  • →Check agent logs: journalctl -u vigilprism-agent (Linux) or Event Viewer (Windows)

Agent registration fails

Symptoms:

  • Agent exits immediately after starting
  • Error: 'Invalid enrollment token'
  • Error: 'Registration rejected'

Solutions:

  • →Generate a new enrollment token from Settings > Agent Builder
  • →Ensure the token hasn't been revoked or expired
  • →Check that agent license limits haven't been exceeded
  • →Verify system clock is synchronized (NTP) - token validation requires accurate time

Agent service won't start

Symptoms:

  • Service fails to start on boot
  • Error: 'Permission denied'
  • Error: 'Address already in use'

Solutions:

  • →Linux: Check service status with 'systemctl status vigilprism-agent'
  • →Ensure the agent binary has execute permissions: chmod +x vigilprism-agent
  • →Verify no other process is using the same port
  • →Check agent has permission to write to its data directory
  • →Windows: Run as Administrator or check service account permissions

Dashboard Issues

Cannot log in to dashboard

Symptoms:

  • Login page rejects valid credentials
  • Error: 'Invalid username or password'
  • Session expires immediately

Solutions:

  • →Verify you're using the correct username (default: admin)
  • →Reset password via CLI: python -m vigilprism.reset_password
  • →Clear browser cookies and cache
  • →Check if account is locked (too many failed attempts)
  • →Verify the database file isn't corrupted

Dashboard loads slowly or times out

Symptoms:

  • Pages take >10 seconds to load
  • Browser shows connection timeout
  • API requests fail intermittently

Solutions:

  • →Check server resource usage (CPU, memory, disk I/O)
  • →Verify database isn't locked by another process
  • →Consider upgrading from SQLite to PostgreSQL for larger deployments
  • →Check network latency between browser and server
  • →Review server logs for slow query warnings

Dashboard shows blank or broken layout

Symptoms:

  • White screen after login
  • CSS styles not loading
  • JavaScript errors in browser console

Solutions:

  • →Hard refresh the page: Ctrl+Shift+R (Windows/Linux) or Cmd+Shift+R (macOS)
  • →Clear browser cache completely
  • →Try a different browser or incognito/private mode
  • →Check browser console for specific error messages
  • →Verify static files are being served correctly

Database Issues

Database locked errors

Symptoms:

  • Error: 'database is locked'
  • Writes fail but reads work
  • Operations timeout after delay

Solutions:

  • →Stop all VigilPrism processes and restart the server
  • →Check for zombie processes: ps aux | grep vigilprism
  • →Ensure only one server instance is running
  • →For high-concurrency needs, migrate to PostgreSQL
  • →Check disk space - SQLite needs space for journaling

Database corruption

Symptoms:

  • Error: 'database disk image is malformed'
  • Missing data after crash
  • Server won't start with database errors

Solutions:

  • →Restore from backup if available
  • →Attempt recovery: sqlite3 vigilprism.db '.recover' | sqlite3 recovered.db
  • →Check filesystem for errors (fsck on Linux)
  • →Ensure proper shutdown procedures are followed
  • →Enable WAL mode for better crash recovery: PRAGMA journal_mode=WAL;

Migration errors on upgrade

Symptoms:

  • Error: 'migration failed'
  • Version mismatch warnings
  • Missing tables or columns

Solutions:

  • →Backup database before any upgrade
  • →Run migrations manually: alembic upgrade head
  • →Check alembic version: alembic current
  • →For stuck migrations, check alembic_version table
  • →Contact support with specific migration error message

Scanning Issues

Vulnerability scan returns no results

Symptoms:

  • Scan completes but shows 0 vulnerabilities
  • Software inventory is empty
  • CVE database shows as empty

Solutions:

  • →Verify CVE database is populated: Settings > CVE Database
  • →Run initial CVE sync: this may take 30+ minutes on first run
  • →Check agent has permission to read package managers (dpkg, rpm, etc.)
  • →For offline systems, import CVE database manually
  • →Verify software inventory is being collected correctly

Audit fails or hangs

Symptoms:

  • Audit stuck at 'Running' status
  • Partial results returned
  • Timeout errors in logs

Solutions:

  • →Check agent connectivity and status
  • →Increase timeout settings if scanning large systems
  • →Review agent logs for specific check failures
  • →Try running individual check categories to isolate the issue
  • →Ensure sufficient system resources on target

Compliance scores seem incorrect

Symptoms:

  • Score doesn't match expected controls
  • Same system shows different scores
  • Manual verification disagrees with automated check

Solutions:

  • →Review individual control mappings in compliance report
  • →Check which checks are mapped to each control
  • →Some controls require manual attestation - verify these are set
  • →Ensure latest audit data is being used (re-run audit if stale)
  • →Report potential false positives for framework mapping review

Network Issues

TLS/SSL certificate errors

Symptoms:

  • Browser shows 'Not Secure' warning
  • Agent fails with certificate validation error
  • Error: 'SSL: CERTIFICATE_VERIFY_FAILED'

Solutions:

  • →For self-signed certs, add to system trust store or use --insecure flag (development only)
  • →Verify certificate hasn't expired: openssl x509 -in cert.pem -text -noout
  • →Ensure certificate covers the hostname being used
  • →Check intermediate certificates are included in chain
  • →For Let's Encrypt, verify auto-renewal is working

Reverse proxy issues

Symptoms:

  • WebSocket connections fail
  • API requests return 502/504 errors
  • Real-time updates don't work

Solutions:

  • →Configure proxy to pass WebSocket upgrade headers
  • →Increase proxy timeout settings for long-running operations
  • →Set correct X-Forwarded-For and X-Forwarded-Proto headers
  • →Nginx: add 'proxy_http_version 1.1;' for WebSocket support
  • →Verify backend server is healthy and responding

Log Locations

When troubleshooting issues, logs are your best friend. Here's where to find them on each platform.

Linux

Server logs (systemd):

journalctl -u vigilprism-server -f

Agent logs (systemd):

journalctl -u vigilprism-agent -f

Log file location:

~/.vigilprism/logs/

Windows

Event Viewer:

Event Viewer → Windows Logs → Application → Filter by "VigilPrism"

Log file location:

C:\ProgramData\VigilPrism\logs\

Service status:

sc query VigilPrismServer

macOS

Console app:

Console.app → Filter by "vigilprism"

Log file location:

~/Library/Logs/VigilPrism/

LaunchAgent status:

launchctl list | grep vigilprism

Still Need Help?

Community Support

For Community Edition users, check our documentation or search existing issues.

Browse Documentation →

Priority Support

Professional and Enterprise customers get priority email and phone support.

View Support Options →
← API ReferenceBack to Docs Home →