Troubleshooting¶
The table below lists common issues and their solutions.
| Issue | Solution |
|---|---|
| Port 5432 already in use | Stop any running PostgreSQL container using docker ps and docker stop <container>.Alternatively, change the host port mapping to -p 5433:5432. |
| Cannot connect to PostgreSQL | Verify environment variables in both backend/.env and backend/migrations/.env.Check container health using docker logs kai. |
| Migrations did not run / tables are missing | Re-run migrations using python backend/migrations/database_setup.py.Ensure CREATE_DATABASE=true is set in the migrations .env file and false in the runtime .env file. |
| Frontend UI shows blank page or 404 | Ensure VITE_BASE_PATH=/kai is set in client/.env.Access the application at http://localhost:23058/kai rather than /. |
| Frontend cannot reach backend | Check client/.env and verify VITE_API_BASE_URL=http://localhost:8000 (in Docker) or 23056 (local).Ensure CORS is configured correctly for your development origin. |
| Credentials cannot be decrypted / Workflow errors | Ensure CREDENTIAL_MASTER_KEY in backend/.env matches the key used when credentials were created. If lost, credentials must be recreated. |
| Kafka Node doesn't receive messages | Verify Kafka broker networking (api.openai.com outbound rule).Ensure topic exists or allow.auto.create.topics is enabled in node settings. |
| VS Code does not load environment variables | If using the provided snippet, ensure your application reads the DOTENV_PATH variable.Alternatively, configure VS Code with "envFile": "${workspaceFolder}/backend/.env". |