Troubleshooting Guide

Common Issues and Solutions

Frontend Issues

1. Application Not Loading

Symptoms:

• Blank white screen
• Loading spinner that never completes
• "Connection refused" error

Solutions:

1. Check if the frontend container is running:

docker ps | grep frontend

2. Verify environment variables are set correctly
3. Check browser console for JavaScript errors
4. Clear browser cache and reload
5. Ensure all API endpoints are accessible

2. Authentication Problems

Symptoms:

• Unable to log in
• Session expires too quickly
• Infinite login loop

Solutions:

1. Clear browser cookies and local storage
2. Check backend authentication logs
3. Ensure correct API endpoints in environment variables
4. Verify CORS settings

Backend Issues

1. API Connection Errors

Symptoms:

• 500 Internal Server Error
• Connection timeout
• CORS errors

Solutions:

1. Check backend logs:

docker logs backend

2. Verify MongoDB connection
3. Check API endpoint configuration
4. Review CORS settings
5. Ensure proper network connectivity

2. Database Connection Issues

Symptoms:

• MongoDB connection errors
• Slow query responses
• Data not persisting

Solutions:

1. Verify MongoDB service is running
2. Check connection string in environment variables
3. Ensure database user has correct permissions
4. Check disk space and memory usage
5. Review MongoDB logs

LLM Backend Issues

1. Model Loading Problems

Symptoms:

• Slow response times
• Memory errors
• Model initialization failures

Solutions:

1. Check system resources (RAM, CPU)
2. Verify model files are present
3. Review LLM backend logs
4. Check GPU availability if applicable
5. Ensure proper environment configuration

2. API Integration Issues

Symptoms:

• Timeout errors
• Invalid responses
• Connection refused

Solutions:

1. Verify API key configuration
2. Check rate limiting settings
3. Review request/response logs
4. Ensure proper network connectivity
5. Validate input/output formats

Docker-related Issues

1. Container Startup Problems

Symptoms:

• Containers failing to start
• Services not connecting
• Resource allocation errors

Solutions:

1. Check Docker logs:

docker-compose logs

2. Verify Docker resource allocation
3. Check port availability
4. Review container dependencies
5. Ensure proper network configuration

2. Volume and Persistence Issues

Symptoms:

• Data loss after container restart
• Permission errors
• Volume mount failures

Solutions:

1. Check volume configurations
2. Verify file permissions
3. Review Docker volume logs
4. Ensure proper path mapping
5. Check disk space availability

Debugging Tools and Techniques

1. Logging

• Enable debug logging in frontend
• Check backend application logs
• Review MongoDB logs
• Monitor Docker container logs
• Use logging aggregation tools

2. Monitoring

• Use Docker stats for resource monitoring
• Monitor API response times
• Track database performance
• Watch system resource usage
• Set up alerts for critical issues

3. Testing

• Run frontend unit tests
• Execute API endpoint tests
• Perform database connection tests
• Validate environment configurations
• Check network connectivity

Getting Help

1. Support Resources

• Review documentation
• Search Stack Overflow

2. Information to Include in Bug Reports

• Error messages and stack traces
• System configuration
• Steps to reproduce
• Relevant logs
• Environment details

3. Emergency Procedures

1. Stop affected services
2. Review recent changes
3. Roll back if needed
4. EMERGENCY
   • Run the command in your ECS terminal docker stop $(docker ps -q) 2>/dev/null || true && docker system prune -af --volumes && docker image prune -af && docker volume prune -f && docker builder prune -af
   • In the root directory, delete the cloned github repository and reclone it and re-install it.