Skip to main content

​
Troubleshooting

If something goes wrong during startup or operations, use the checks and fixes below to quickly isolate the problem. Unless noted otherwise, Docker commands below work in Linux/macOS shells and Windows PowerShell.

​
1) Container fails to start

Check recent logs for the failing service: These commands are the same in Linux/macOS and Windows PowerShell.
Common causes and fixes:
  • Database not ready: wait a minute and retry docker compose exec api python manage.py migrate
  • Missing env vars: open Core/.env and confirm required keys are present
  • Wrong working directory: ensure you run compose commands from Core/

​
2) Database & migrations

If migrations fail or partially applied, try: This command is the same in Linux/macOS and Windows PowerShell.
If pgvector extension is missing, install it inside the API container: This command is the same in Linux/macOS and Windows PowerShell.

​
3) Authentication / Admin user

If you cannot sign in with the superuser:
  • Confirm SUPERUSER_USERNAME, SUPERUSER_PASSWORD, SUPERUSER_EMAIL in .env
  • Check API logs: docker compose logs api to see account creation messages

​
4) WebSockets & real-time notifications

If notifications or WebSocket features do not work:
  • Confirm API is running and reachable from the frontend
  • Check VITE_API_URL and WebSocket URL settings in .env
  • For local testing, WebSocket URL often looks like ws://localhost:9100/ws/notifications/

​
5) When all else fails

  • Restart the stack:
These commands are the same in Linux/macOS and Windows PowerShell.
  • Inspect container state: docker compose ps and docker compose top
  • Search logs for stack traces and post the error if you need help
If you want, copy a short excerpt of the relevant logs and I can help interpret them.