Troubleshooting Guide

​

Quick Fixes

​

”I can’t access the web interface”

1. Check if the containers are running:

docker ps | grep kodus-web-prod

2. Verify the ports are correctly mapped:

docker port kodus-web-prod

3. Check the web container logs:

docker logs kodus-web-prod

​

“Git webhooks aren’t working”

1. Verify your domain setup:

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

2. Check the orchestrator logs for webhook attempts:

docker logs kodus-orchestrator-prod | grep webhook

3. Verify your reverse proxy configuration:

sudo nginx -t

​

“Database connection issues”

1. Check database container status:

docker ps | grep db_kodus_postgres
docker ps | grep db_kodus_mongodb

2. Verify database logs:

docker logs db_kodus_postgres
docker logs db_kodus_mongodb

3. Test database connections:

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

​

“Migration failed due to missing vector type”

If you encounter the error “type vector does not exist” during migrations, this is because the pgvector extension is not enabled in your PostgreSQL database. Here’s how to fix it:

1. Connect to your PostgreSQL database:

docker exec -it 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 exec -it kodus-api-prod npm run migration:run

If you’re still experiencing issues, you can verify the extension is properly installed:

SELECT * FROM pg_extension WHERE extname = 'vector';

​

Common Problems

​

RabbitMQ Issues

If you’re seeing message queue errors:

1. Check RabbitMQ status:

docker logs rabbitmq-prod

2. Access the management console at http://localhost:15672 to verify queues and connections

3. Restart the service if needed:

docker restart rabbitmq-prod

​

Resource Problems

If services are slow or crashing:

1. Check resource usage:

docker stats

2. Verify container limits:

docker inspect kodus-orchestrator-prod | 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
• Email support at support@kodus.io