Troubleshooting¶

Common issues and solutions when deploying and operating AegisAI.

Service Won't Start¶

App container exits immediately¶

Symptoms: docker compose ps shows app as exited.

Diagnosis:

docker compose logs app --tail 50

Common causes:

Error	Solution
`connection refused` to postgres	Wait for postgres health check; verify `DATABASE_URL`
`alembic.util.exc.CommandError`	Check migration conflicts; run `alembic upgrade head` manually
`ModuleNotFoundError`	Rebuild image: `docker compose build --no-cache app`
Port 8000 in use	Change port mapping or stop conflicting process

Frontend not accessible¶

Symptoms: http://localhost:5173 returns connection refused.

docker compose logs frontend --tail 30

Error	Solution
`EADDRINUSE`	Port 5173 occupied; change mapping
`npm ERR!`	Rebuild: `docker compose build frontend`
Proxy errors	Verify `VITE_PROXY_TARGET=http://app:8000`

Database Issues¶

Cannot connect to PostgreSQL¶

# Check postgres is running
docker compose ps postgres

# Test connection
docker compose exec postgres pg_isready -U aegisai

# Check logs
docker compose logs postgres --tail 20

Solutions:

Ensure postgres service is healthy before app starts
Verify credentials in DATABASE_URL match POSTGRES_USER/POSTGRES_PASSWORD
Check volume permissions: docker volume inspect aegisai_postgres_data

Migration failures¶

# Check current revision
docker compose exec app poetry run alembic current

# View migration history
docker compose exec app poetry run alembic history

# Force upgrade
docker compose exec app poetry run alembic upgrade head

Backup first

Always back up the database before running migrations on production data.

Authentication Issues¶

Cause	Solution
SIEM enabled with unreachable URL	Set `SIEM_ENABLED=false` or configure real Splunk/ELK/syslog
Wrong credentials	Run `init_super_admin.py --force-sync`; verify `SUPER_ADMIN_*` in `.env`
Using `ADMIN_API_KEY` instead of password	Login form expects email + password, not admin API key

Cause	Solution
`redirect_uri mismatch`	Match `SSO_CALLBACK_URL` exactly in IdP settings
`invalid_state`	Enable cookies; retry within 10 minutes
No SSO buttons	Call `GET /auth/sso/providers`; verify `*_ENABLED=true`
Auto-provision disabled	Pre-create user or set `SSO_AUTO_PROVISION=true`

See SSO Configuration.

Cause	Solution
Wrong email/password	Verify `SUPER_ADMIN_EMAIL` and `SUPER_ADMIN_PASSWORD` in env
User blocked	Admin unblocks via `POST /users/{id}/unblock`
Super admin not created	Run `docker compose exec app poetry run python scripts/init_super_admin.py --force-sync`
Password out of sync	Set `SUPER_ADMIN_SYNC_PASSWORD=true` and restart app

API returns 401 with API key¶

# Test API key
curl http://localhost:8000/api/v1/status \
  -H "X-API-Key: your-key-here" \
  -v

Cause	Solution
Missing header	Add `X-API-Key` header
Invalid key	Verify key from tenant creation or login response
Revoked key	Create new key via `POST /api/v1/api-keys`
Wrong tenant	Ensure key belongs to the correct tenant

JWT expired¶

Symptoms: Dashboard redirects to login after period of inactivity.

Solution: Log in again. JWT TTL is configured in user_service.SESSION_TTL_HOURS.

SIEM Issues¶

SIEM errors in logs (`Name or service not known`)¶

Symptoms: App logs show SIEM send attempt failed; login may slow down on older builds.

Solution:

SIEM_ENABLED=false

Or configure reachable endpoints. See SIEM Integration.

Inline comments in .env

Do not put comments on the same line as values (SIEM_FORMAT=cef # comment). Docker/env parsers may include the comment in the value.

Deploy Issues¶

`container is running: stop the container before removing`¶

Symptoms: GitHub Actions or ./deploy.sh fails during docker compose up.

Solution: Use the latest deploy.sh (stops app/frontend before recreate) or manually:

docker compose -f docker-compose.prod.yml stop app frontend
docker compose -f docker-compose.prod.yml up --build -d

OPA Issues¶

OPA not ready / policies not loaded¶

Symptoms: App logs show OPA not ready warnings; policy checks use fallback engine.

# Check OPA health
curl http://localhost:8181/health

# Check OPA logs
docker compose logs opa --tail 20

# Restart OPA
docker compose restart opa app

Solutions:

Ensure opa container is running
Verify OPA_URL=http://opa:8181 in app environment
Check policies/templates/ directory is mounted
App retries OPA connection 10 times at startup (20 seconds total)

Policy check always allows/denies¶

# List loaded templates
curl http://localhost:8000/api/v1/policies/templates \
  -H "X-API-Key: <key>"

# Test specific check
curl -X POST http://localhost:8000/api/v1/policies/check \
  -H "X-API-Key: <key>" \
  -H "Content-Type: application/json" \
  -d '{"agent_id": "<uuid>", "action": "read_data", "resource": "customer_pii", "context": {}}'

WebSocket Issues¶

Dashboard not receiving real-time updates¶

Symptoms: Connection indicator shows offline; no toast notifications.

Diagnosis:

Open browser DevTools → Network → WS tab
Check WebSocket connection to /api/v1/ws?token=...

Cause	Solution
Invalid JWT	Log in again to refresh token
Proxy not configured	Add WebSocket upgrade headers to reverse proxy
Redis down	Check `docker compose ps redis`
User inactive	Admin unblocks user

Nginx WebSocket config:

location /api/v1/ws {
    proxy_http_version 1.1;
    proxy_set_header Upgrade $http_upgrade;
    proxy_set_header Connection "upgrade";
    proxy_read_timeout 86400;
}

Redis Issues¶

Real-time events not working¶

# Test Redis
docker compose exec redis redis-cli ping
# Expected: PONG

# Check memory
docker compose exec redis redis-cli INFO memory

Solutions:

Restart Redis: docker compose restart redis
Check REDIS_URL matches Redis container hostname
Enable persistence: redis-server --appendonly yes

Performance Issues¶

Slow API responses¶

Check	Command
Container resources	`docker stats`
DB connections	`docker compose exec postgres psql -U aegisai -c "SELECT count(*) FROM pg_stat_activity;"`
App logs	`docker compose logs app --tail 100`

Solutions:

Increase Uvicorn workers: --workers 4
Add PostgreSQL connection pooling
Scale Redis memory
Check for N+1 queries in audit log listing

High memory usage¶

Anomaly detector model loaded in memory — normal for ML operations
Limit audit log query limit parameter
Configure Redis maxmemory policy

Export Issues¶

Async export stuck in pending¶

# Check job status
curl http://localhost:8000/api/v1/audit/export/status/<job_id> \
  -H "X-API-Key: <key>"

# Check storage directory
docker compose exec app ls -la /app/storage/

Solutions:

Ensure storage/ volume is mounted and writable
Check app logs for background task errors
Restart app container to clear stuck tasks

Webhook Issues¶

Invalid webhook signature¶

# Verify signing
python -c "
from aegisai.integrations.webhook.signature import sign_payload
import json
body = json.dumps({'event': 'agent.action', 'payload': {}}).encode()
print(sign_payload(body, 'webhook-secret-key'))
"

Solutions:

Ensure WEBHOOK_SECRET matches on sender and server
Sign the raw request body bytes, not a re-serialized JSON
Include X-Webhook-Signature header

Getting Help¶

Diagnostic Bundle¶

Collect information for support requests:

# Service status
docker compose ps > diagnostic.txt

# App logs
docker compose logs app --tail 200 >> diagnostic.txt

# Health checks
curl -s http://localhost:8000/api/v1/health >> diagnostic.txt
curl -s http://localhost:8000/api/v1/health/ready >> diagnostic.txt

# Environment (redact secrets)
docker compose exec app env | grep -v SECRET | grep -v PASSWORD >> diagnostic.txt

Log Levels¶

Increase verbosity for debugging:

# In docker-compose.yml or .env
LOG_LEVEL=DEBUG

Restart the app container after changing log level.

Troubleshooting¶

Service Won't Start¶

App container exits immediately¶

Frontend not accessible¶

Database Issues¶

Cannot connect to PostgreSQL¶

Migration failures¶

Authentication Issues¶

Login hangs on loading spinner¶

SSO login fails¶

Login returns 401¶

API returns 401 with API key¶

JWT expired¶

SIEM Issues¶

SIEM errors in logs (Name or service not known)¶

Deploy Issues¶

container is running: stop the container before removing¶

OPA Issues¶

OPA not ready / policies not loaded¶

Policy check always allows/denies¶

WebSocket Issues¶

Dashboard not receiving real-time updates¶

Redis Issues¶

Real-time events not working¶

Performance Issues¶

Slow API responses¶

High memory usage¶

Export Issues¶

Async export stuck in pending¶

Webhook Issues¶

Invalid webhook signature¶

Getting Help¶

Diagnostic Bundle¶

Log Levels¶

Related Documentation¶

SIEM errors in logs (`Name or service not known`)¶

`container is running: stop the container before removing`¶