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".