This page lists the most common deployment issues and how to resolve them. For runtime diagnostics, GET /health?deep=true reports database, disk, gcloud, and security-posture status, and every error response carries an X-Correlation-ID you can quote to support.
| Issue | Cause | Resolution |
|---|
| Backend exits with “production startup blocked — N security config errors” | A fail-fast condition tripped (missing HMAC_KEY/API_KEY/ENCRYPTION_KEY, STORAGE_MODE=compat, dev mode on, a tenant-bypass flag, a weak secret, or the DB unreachable) | Fix the reported setting (see Configuration). Emergency only: SECURITY_PERMIT_INSECURE_BOOT=true (audited, unsafe) |
python main.py doesn’t start the web server | main.py is a legacy CLI IAM scanner, not the backend | Start python -m uvicorn api.app:app --host 0.0.0.0 --port 9900 |
ModuleNotFoundError for extension... | extension/ not on PYTHONPATH | Run from the repo root, or use the provided launchers / containers which set PYTHONPATH |
| Backend fails to import with odd errors | Stray stub files at the project root shadowing real packages | Remove/quarantine any stray fastapi.py, boto3/, google/ stubs at the root |
| Issue | Cause | Resolution |
|---|
| Scans rejected before they start / slow timeouts | GCP Application Default Credentials expired | gcloud auth application-default login, or set GOOGLE_APPLICATION_CREDENTIALS |
| AWS scan raises an import error immediately | boto3 / botocore not installed | pip install boto3 botocore (already in requirements.txt) |
| Azure scan completes but inventory is empty | Azure SDKs missing → graceful empty result | Install the Azure SDK dependencies, then re-scan |
| Scan completes but no findings | Read permissions missing or wrong scope | Run the Pre-scan Permission Check; widen scope or grant read roles |
| Issue | Cause | Resolution |
|---|
| Port already in use (9900 / 8200 / 7700) | A previous process is still listening | start-servers.bat / stop-servers.sh free the ports; or change PORT / LICENSE_PORT / DB_PORT |
| Vite dev server fails to start on 8200 | The frontend dev port is fixed (strictPort) | Free port 8200 — it will not auto-increment |
| CORS errors in production | FRONTEND_ORIGINS unset → falls back to dev origins | Set FRONTEND_ORIGINS=https://your-host (CSV). In local dev the Vite proxy avoids CORS |
| Issue | Cause | Resolution |
|---|
Everything returns a license error (403/423) | License invalid or locked | Activate a valid license; check the license server is reachable over HTTPS |
| License validation silently disabled | REDCLOUD_LICENSE_SECRET unset | Set the same secret on the backend and the license server |
| Issue | Cause | Resolution |
|---|
| Scheduled scans don’t fire | Scheduler auto-start failed at boot | Call POST /scheduler/start, or check the logs for the scheduler warning |
| Need a deep health check | — | GET /health?deep=true for component diagnostics; GET /metrics for Prometheus |
When you contact support, include the scan ID and the X-Correlation-ID from the error — they let the team trace the exact request in the audit log. See Support.
