Skip to content

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