Troubleshooting Guide

​

Quick Fixes

​

”Run diagnostics”

cd kodus-installer
./scripts/doctor.sh

​

”I can’t access the web interface”

1. Check if the containers are running:

docker-compose ps kodus-web

2. Verify the ports are correctly mapped:

docker-compose port kodus-web 3000

3. Check the web container logs:

docker-compose logs kodus-web

​

“Edge Runtime errors in kodus-web logs”

1. Update to the latest kodus-web image (re-run the installer or run docker-compose pull kodus-web and docker-compose up -d).
2. If you are building from source, make sure auth/server routes run on the Node.js runtime (set export const runtime = "nodejs" and avoid runtime = "edge" on those routes).
3. Rebuild and restart the container.

​

”Git webhooks aren’t working”

1. Verify your domain setup:

curl -I https://your-domain.com

2. Check the webhooks logs for webhook attempts:

docker-compose logs webhooks | grep webhook

3. Verify your reverse proxy configuration:

sudo nginx -t

​

“Database connection issues”

1. Check database container status:

docker-compose ps db_kodus_postgres
docker-compose ps db_kodus_mongodb

2. Verify database logs:

docker-compose logs db_kodus_postgres
docker-compose logs db_kodus_mongodb

3. Test database connections:

docker-compose exec db_kodus_postgres psql -U $API_PG_DB_USERNAME -d $API_PG_DB_DATABASE
docker-compose exec db_kodus_mongodb mongosh -u $API_MG_DB_USERNAME -p $API_MG_DB_PASSWORD

​

“Migration failed due to missing vector type”

1. Connect to your PostgreSQL database:

docker-compose exec db_kodus_postgres psql -U $API_PG_DB_USERNAME -d $API_PG_DB_DATABASE

2. Enable the pgvector extension:

CREATE EXTENSION IF NOT EXISTS vector;

3. After enabling the extension, try running your migrations again:

docker-compose exec api npm run migration:run

SELECT * FROM pg_extension WHERE extname = 'vector';

​

Common Problems

​

RabbitMQ Issues

1. Check RabbitMQ status:

docker-compose logs rabbitmq

2. Access the management console at http://localhost:15672 to verify queues and connections
3. Restart the service if needed:

docker-compose restart rabbitmq

​

Resource Problems

1. Check resource usage:

docker stats

2. Verify container limits:

docker inspect $(docker-compose ps -q api) | grep -A 5 "Resources"

3. Adjust resource limits in docker-compose.yml if needed

​

Getting Help

​

What to Include in Support Requests

• The exact error message
• Relevant logs from affected services
• Your deployment method (CLI, VM, etc.)
• Steps to reproduce the issue

​

Where to Get Help

• Discord Community
• GitHub Issues