Troubleshooting
Diagnose and resolve common StavenCTL installation and runtime issues.
This page covers the most common issues encountered when installing and running StavenCTL.
Configuration File Not Found
The agent requires the configuration file at:
/etc/stavenctl/config.confVerify that it exists.
ls -l /etc/stavenctl/config.confIf the file is missing, reinstall StavenCTL or restore the configuration from a backup.
Database Connection Failed
If initialization or migrations fail, verify that PostgreSQL is running.
sudo systemctl status postgresqlConfirm the database connection string in:
/etc/stavenctl/config.confDATABASE_URL=postgres://username:password@127.0.0.1:5432/database?sslmode=disableThen retry initialization.
sudo stavenctl-agent migrationRedis Connection Failed
Ensure Redis is running.
sudo systemctl status redisVerify the Redis settings.
REDIS_HOST=127.0.0.1
REDIS_PORT=6379
REDIS_PASSWORD=
REDIS_DB=0Restart Redis if necessary.
sudo systemctl restart redisAgent Service Not Running
Check the service status.
sudo systemctl status stavenctl-agentRestart the service.
sudo systemctl restart stavenctl-agentView recent logs.
sudo journalctl -u stavenctl-agent -n 100 --no-pagerServer Service Not Running
Check the backend server.
sudo systemctl status stavenctl-serverRestart it.
sudo systemctl restart stavenctl-serverView logs.
sudo journalctl -u stavenctl-server -n 100 --no-pagerNginx Service Failed
Verify the managed Nginx configuration.
sudo /usr/local/stavenctl/nginx/sbin/stavenctl-nginx -tCheck the service.
sudo systemctl status stavenctl-nginxReload configuration.
sudo systemctl reload stavenctl-nginxRestart if required.
sudo systemctl restart stavenctl-nginxInspect logs.
sudo journalctl -u stavenctl-nginx -n 100 --no-pagerDatabase Migration Failed
Run migrations again.
sudo stavenctl-agent migrationIf the error persists, verify:
- PostgreSQL is running.
DATABASE_URLis correct.- The database exists.
- The configured user has sufficient privileges.
Unable to Create Administrator
Creating the initial administrator requires root privileges.
sudo stavenctl-agent create-adminIf the command fails, ensure:
- The configuration file is valid.
- PostgreSQL is accessible.
- Database migrations completed successfully.
License Activation Failed
Check the current license status.
stavenctl-agent license statusVerify the installed license.
stavenctl-agent license verifyClear the cached license if necessary.
stavenctl-agent license clear-cacheActivate the license again.
stavenctl-agent license activateCheck All Services
Verify every required service is running.
sudo systemctl status postgresql
sudo systemctl status redis
sudo systemctl status stavenctl-server
sudo systemctl status stavenctl-agent
sudo systemctl status stavenctl-nginxUseful Log Locations
| Component | Log Source |
|---|---|
| Agent | journalctl -u stavenctl-agent |
| Server | journalctl -u stavenctl-server |
| Nginx | journalctl -u stavenctl-nginx |
| PostgreSQL | journalctl -u postgresql |
| Redis | journalctl -u redis |
Collect Diagnostic Information
When requesting support, include the following information.
stavenctl-agent --version
sudo systemctl status stavenctl-agent
sudo systemctl status stavenctl-server
sudo systemctl status stavenctl-nginx
sudo journalctl -u stavenctl-agent -n 100 --no-pager
sudo journalctl -u stavenctl-server -n 100 --no-pager
sudo journalctl -u stavenctl-nginx -n 100 --no-pagerThese commands provide enough information to diagnose most installation, configuration, service, database, and runtime issues.