Troubleshooting

This guide helps you diagnose and resolve common issues with AI Controller.

Quick Diagnostics

Check System Status

1. Service Status: Verify AI Controller is running

   • Web interface accessible at configured URL
   • Check service logs for startup errors

2. Configuration: Validate your server.cfg settings

   • Database connectivity (check connection string)
   • Port conflicts (default: varies by deployment)
   • SSL/TLS certificate paths (if using HTTPS)

3. Logs: Review application logs for errors

   • Access via Admin → Logs in web interface
   • Check container logs for Docker deployments
   • Application logs in installation directory

Common Issues

Authentication Problems

Cannot log in to web interface

• Verify credentials are correct
• Check if account is locked after failed attempts
• Ensure cookies are enabled in browser

API key not working

• Verify key hasn't expired or been deleted
• Check key has required permissions
• Ensure correct API endpoint URL
• Confirm key is assigned to correct provider

Provider Connection Issues

Provider API errors

• Verify API keys are valid and active
• Check network connectivity to provider endpoints
• Ensure required models are available/enabled
• Review rate limits and quotas

Local model integration failing

• Confirm endpoint URL is accessible
• Check hardware resources (memory, GPU)
• Verify model file integrity

Performance Issues

Slow response times

• Check cache configuration and hit rates
• Monitor provider response times in logs
• Verify network latency to providers
• Review system resource usage

High memory usage

• Check concurrent request limits
• Review cache size settings
• Monitor for memory leaks in logs

Deployment-Specific Issues

Docker

Container fails to start

docker logs ai-controller

• Check environment variables in docker-compose.yml
• Verify volume mounts are correct
• Ensure database container is running first

Windows Service

Service won't start

• Check Windows Event Viewer for errors
• Verify service account permissions
• Ensure all dependencies are installed

Linux Systemd

Service fails with exit code

• Review journal: journalctl -u aic -e
• Check file permissions in /opt/aic
• Verify systemd service file configuration

Getting Help

If you cannot resolve an issue:

1. Gather Information

   • Error messages from logs
   • Steps to reproduce the issue
   • System configuration details
   • Screenshot of the problem (if applicable)

2. Contact Support

   • Email: support@ai-controller.ai
   • Include all gathered information
   • Specify AI Controller version and deployment type

---

Updated: 2025-05-27