Troubleshooting
Health Checks
Checking Service Status
docker compose ps
All services should show healthy or running. If a service shows unhealthy or is restarting, check its logs.
API Health Check
curl http://localhost/api/v1/version
A successful response confirms the backend is running and reachable through Nginx.
Database Connectivity
# All-in-one deployment
docker compose exec postgres pg_isready -U orbisid
# Check database logs
docker compose logs postgres
Common Issues
Cannot Access the Web UI
| Symptom | Possible Cause | Solution |
|---|---|---|
| Browser shows "Connection refused" | Nginx or Docker not running | Run docker compose ps and start any stopped services |
| Browser shows 502 Bad Gateway | Backend is starting or has crashed | Wait 60 seconds for startup, then check docker compose logs backend |
| Browser shows 404 | Incorrect URL or frontend not built | Verify you're accessing the root URL (e.g., http://localhost) |
Cannot Log In
| Symptom | Possible Cause | Solution |
|---|---|---|
| "Invalid credentials" | Wrong password | Use default admin / ChangeMe123! for first login |
| "Account locked" | Too many failed attempts | Wait 30 minutes for auto-unlock, or have another admin reset the account |
| SSO button missing | OIDC not configured | Configure OIDC at Administration > Authentication (Enterprise) |
| SSO login fails | Incorrect OIDC configuration | Verify Issuer URL, Client ID, Client Secret, and Redirect URI |
Scan Failures
| Symptom | Possible Cause | Solution |
|---|---|---|
| Scan status: FAILED | Connection error to target | Check scan logs for details. Verify network connectivity and credentials |
| "Connection timed out" | Firewall blocking access | Ensure outbound ports are open (389/636 for AD, 22 for Linux, 1433 for SQL Server) |
| "Authentication failed" | Wrong credentials | Verify the credential in OrbisID matches the target system |
| "Requires Scan Agent" | Custom Script system with no agent | Deploy a Scan Agent for Custom Script and PAM Vault Script systems |
| Scan stays "Queued" | No available scan worker or agent | Check if agents are online; restart the backend if the built-in worker is stuck |
Database Issues
| Symptom | Possible Cause | Solution |
|---|---|---|
| Backend fails to start with migration error | Flyway migration conflict | Check docker compose logs backend for the exact migration error. Do not manually modify the database schema. |
| "Too many connections" | Connection pool exhausted | Restart the backend. If persistent, check for runaway queries. |
| Slow queries | Large dataset without indexes | Contact OrbisID support |
Encryption Key Issues
| Symptom | Possible Cause | Solution |
|---|---|---|
| "Decryption failed" errors | ENCRYPTION_KEY changed or incorrect | Restore the original ENCRYPTION_KEY from your backup |
| Credentials show as blank | Key mismatch | The encryption key must match the one used when credentials were created |
danger
If you lose the ENCRYPTION_KEY, all encrypted credentials are unrecoverable. You will need to re-enter all credential passwords.
Viewing Logs
Backend Logs
# Real-time logs
docker compose logs -f backend
# Last 100 lines
docker compose logs --tail 100 backend
Frontend Logs
docker compose logs -f frontend
Nginx Logs
docker compose logs -f nginx
Log Levels
The backend log level can be adjusted at runtime through the API:
# View current log level
curl http://localhost/api/v1/log-management/server/level \
-H "X-Session-Id: your-session-id"
# Set to DEBUG for troubleshooting
curl -X PUT http://localhost/api/v1/log-management/server/level \
-H "X-Session-Id: your-session-id" \
-H "Content-Type: application/json" \
-d '{"level": "DEBUG"}'
Remember to set it back to INFO after troubleshooting.
Performance
Slow Scans
- Check the scan priority of systems. Lower priority numbers are scanned first.
- Large Active Directory domains with thousands of accounts take longer to scan.
- Ensure the backend has adequate memory (8 GB+ recommended for large environments).
Slow UI
- Clear browser cache and reload
- Check backend response times in the browser's developer tools (Network tab)
- Ensure the PostgreSQL instance has adequate resources
Getting Help
If you cannot resolve an issue using this guide:
- Collect the relevant logs (
docker compose logs > orbisid-logs.txt) - Note the OrbisID version (
GET /api/v1/version) - Contact OrbisID support with the logs and version information