Troubleshooting

Dashboard won't start, 'database connection refused'

Ensure the database container is healthy before the app container starts. Run `docker compose ps` to check container status. If the db shows as unhealthy, check `docker compose logs db`.

License activation fails with 'key not found'

Check that you copied the full key without extra spaces. License keys are case-sensitive. If the issue persists, contact support@infrapilot.org with your account email.

Agent is offline / not appearing in dashboard

Verify the agent can reach your dashboard URL on port 443 (or 80). Check `systemctl status infrapilot-agent` and `journalctl -u infrapilot-agent -n 50` for error messages. Firewall rules between agent server and dashboard are the most common cause.

Nginx proxy not routing traffic correctly

Confirm the container target port matches what the service actually listens on. Use `docker compose logs nginx` to inspect routing errors. Check that SSL certificates are valid via Settings → Security.

High memory usage

InfraPilot retains recent log data in memory for fast search. Adjust the LOG_RETENTION_MB env variable (default: 256) in your .env to reduce memory pressure. Container will automatically prune older entries.

Forgot dashboard admin password

Use the CLI reset tool: `docker compose exec app infrapilot reset-password --email your@email.com`. A reset link will be sent to your registered email address.