Troubleshooting

Startup Issues

"Application startup failed: Invalid license file format"

Cause: The license.key file exists but is empty or corrupted.

Fix: Either remove the file (Free tier) or replace with a valid license:

rm license.key
touch license.key    # empty file = Free tier
docker compose restart backend

Backend keeps restarting

Check logs:

docker compose logs backend | tail -30

Common causes:

  • PostgreSQL not ready yet → wait 30 seconds and check again
  • Invalid .env values → check POSTGRES_PASSWORD and JWT_SECRET are set
  • Port conflict → another service is using the same port

"Port already in use"

Another service is using the port. Find it:

sudo lsof -i :3000

Change the port in .env:

PORT=8080

Then restart:

docker compose down && docker compose up -d

Database connection error

Ensure PostgreSQL is healthy:

docker compose ps

If postgres shows "unhealthy":

docker compose logs postgres | tail -20

Common fix: POSTGRES_PASSWORD in .env must match across DATABASE_URL.

Login Issues

Forgot admin password

docker compose down
# Set new password in .env:
nano .env
# Change DEFAULT_ADMIN_PASSWORD=NewPassword123

# Delete database and start fresh:
docker compose down -v
docker compose up -d

Warning: -v deletes all data. Backup first if you have important traces.

"Invalid email or password"

Verify credentials:

docker compose logs backend | grep -i "admin\|password"

If DEFAULT_ADMIN_PASSWORD was empty, the auto-generated password is printed in the logs on first startup only.

Dashboard Issues

"Unable to connect to the server"

The dashboard cannot reach the backend API.

If accessing remotely: Make sure you're using the server IP, not localhost. All traffic goes through the gateway (nginx) on one port.

Check services:

docker compose ps
# All 4 should be "healthy"

Check gateway:

docker compose logs gateway | tail -10

Traces not appearing

  1. Check agent connection: your SDK must point to the correct endpoint
  2. Check API key: is it valid and not expired?
  3. Check trace limits: Free tier = 500 traces/day
docker compose logs backend | grep "trace\|limit\|403"

Live updates not working (SSE)

SSE requires a persistent connection. If using a reverse proxy in front of Aberon, ensure it doesn't buffer or timeout SSE connections:

  • proxy_buffering off
  • proxy_read_timeout 86400s

The included nginx gateway already has these settings.

Policy Issues

Guardrail not blocking

  1. Is the policy active? Check Dashboard → Policies
  2. Is it targeting the right agent? Check target_agent_id
  3. Check priority — a higher-priority policy might be allowing it
  4. Check agent's capture_mode — metadata_only doesn't capture content for PII scanning

PII not being detected

PII detection uses the English language model (en_core_web_lg). Non-English text may have lower detection accuracy.

Check what was detected:

docker compose logs backend | grep "pii"

Approval requests timing out immediately

Check APPROVAL_TIMEOUT_SECONDS in .env (default: 300 seconds = 5 minutes). Increase if reviewers need more time.

Performance

Slow dashboard

  • Check database size: Free tier retains 14 days of data
  • Reduce TRACE_RETENTION_DAYS if you have too many traces
  • Increase WORKERS in .env (default: 2)

High memory usage

  • spaCy NLP model (en_core_web_lg) uses ~400 MB RAM
  • PostgreSQL uses ~200 MB minimum
  • Recommended: 4 GB RAM for production

Backup Before Troubleshooting

Always backup before destructive changes. See Backup & Restore for details.

docker compose exec postgres pg_dump -U aberon aberon | gzip > backup.sql.gz

Getting Help

  • Free tier: This documentation
  • Team: support@aberon.ai
  • Enterprise: Dedicated support channel + SLA

Include these in your support request:

docker compose ps
docker compose logs backend | tail -50
cat .env | grep -v PASSWORD | grep -v SECRET | grep -v KEY
cat VERSION