Troubleshooting Guide
Common Issues
API won’t start
- Check database connection:
DATABASE_URL is correct
- Verify PostgreSQL is running with pgvector extension
- Check port 8080 is not in use:
netstat -an | grep 8080
- Review logs for specific errors
Search returns no results
- Ensure repositories are synced
- Check data exists:
curl http://localhost:8080/api/v1/repositories
- Try simpler queries first
- Check embeddings are generated
Rate limiting too strict
- Adjust
API_RATE_LIMIT in settings
- Modify rate limits in route decorators
- Use multiple IPs for higher throughput
- Check database indexes are created
- Verify pgvector extension is installed
- Review query complexity
- Consider adding more workers
Azure DevOps Authentication
Issue: “No credentials were supplied” for Negotiate
Cause: System doesn’t have Kerberos credentials.
Fix: Use PAT or Basic auth (disable NTLM configuration).
Issue: “Authentication failed”
Causes:
- Wrong username/password
- Account locked or disabled
- Insufficient permissions
- PAT expired
Fix: Verify credentials, check account status, create new PAT.
Issue: “SSL certificate problem”
Cause: Self-signed certificate.
Fix: Set AZUREDEVOPS_SSL_VERIFY=false (only for trusted networks!).
Recommended Configuration for Azure DevOps
# Using Personal Access Token (RECOMMENDED)
AZUREDEVOPS_URL=https://dev.azure.com/your-organization/
AZUREDEVOPS_USERNAME=pat
AZUREDEVOPS_PASSWORD=your_personal_access_token_here
AZUREDEVOPS_USE_NTLM=false
AZUREDEVOPS_SSL_VERIFY=false
Debug Mode
Enable debug logging:
LOG_LEVEL=DEBUG python -m src.mcp_server