Known Issues & Troubleshooting

Common Issues

Connection Errors

Issue: "Connection refused" when connecting to cortex-api

Solution: 1. Verify the API is running: curl http://localhost:8080/health 2. Check Traefik routing configuration 3. Ensure firewall rules allow the connection

Indexing Failures

Issue: "Failed to index repository"

Solution: 1. Check disk space on Qdrant nodes 2. Verify Git repository is accessible 3. Check indexer logs: journalctl -u cortex-indexer

Authentication Issues

Issue: "Invalid token" or "Unauthorized"

Solution: 1. Clear browser cookies and re-authenticate 2. Verify Zitadel configuration 3. Check token expiration settings

Slow Search Performance

Issue: Queries taking > 5 seconds

Solution: 1. Check Qdrant cluster health 2. Verify network latency between services 3. Consider increasing Qdrant replicas

Reporting Issues

For new issues, please file a ticket in GitLab with: - Steps to reproduce - Expected vs actual behavior - Relevant logs - Environment details (versions, config)

FAQ

Q: Why are some files not indexed? A: Check .cortexignore file for exclusion patterns.

Q: How do I re-index a repository? A: Use cortex index --force --repo /path/to/repo

Q: How do I clear the vector cache? A: Delete the collection in Qdrant and re-index.