Troubleshooting Guide

Symptoms:

• Error message: "Could not connect to PostgreSQL"
• Installation stops at database setup step
• Timeout errors during database initialization

Solution:

Verify PostgreSQL is running: `sudo systemctl status postgresql`. Check credentials in `.env` file match your database. Ensure PostgreSQL accepts connections from localhost. Test connection: `psql -U brainpredict -d brainpredict_db -h localhost`. If firewall is enabled, allow port 5432.

Symptoms:

• Error: "Model initialization timeout"
• Installation completes but models show as "Not Ready"
• High CPU usage during model loading

Solution:

Ensure system meets minimum requirements (32GB RAM for production). Check available disk space (need 500GB+ free). Increase timeout in config: `MODEL_INIT_TIMEOUT=600`. Restart services: `pm2 restart all`. Monitor logs: `tail -f /opt/brainpredict/logs/model-init.log`.

Symptoms:

• API requests timeout
• Dashboard shows "Loading..." for extended periods
• High memory usage (>90%)

Solution:

Check system resources: `htop` or `top`. Restart backend: `pm2 restart brainpredict-backend`. Clear Redis cache: `redis-cli FLUSHDB`. Optimize database: `VACUUM ANALYZE;` in PostgreSQL. Scale horizontally by adding more workers in `pm2.config.js`.

Symptoms:

• System becomes unresponsive
• Out of memory errors in logs
• Swap usage at 100%

Solution:

Identify memory-intensive processes: `ps aux --sort=-%mem | head`. Restart services to free memory: `pm2 restart all`. Increase swap space if needed. Consider upgrading RAM or reducing number of loaded models. Enable lazy loading in config: `LAZY_LOAD_MODELS=true`.

Symptoms:

• Login fails with correct username/password
• Session expires immediately
• Redirect loop after login

Solution:

Clear browser cookies and cache. Verify user exists in database: `SELECT * FROM users WHERE email='user@example.com';`. Reset password via CLI: `python manage.py reset-password user@example.com`. Check JWT secret is set in `.env`: `JWT_SECRET_KEY`. Verify Redis is running for session storage.

Symptoms:

• Error: "Invalid license key"
• Features disabled despite valid subscription
• License API returns 401 Unauthorized

Solution:

Verify license key in admin panel. Check license API is running: `curl https://localhost:8001/api/health`. Ensure mTLS certificates are valid: `openssl x509 -in /opt/brainpredict/license-api/certs/server.crt -noout -dates`. Sync license from Stripe: `python manage.py sync-licenses`. Contact support@brainpredict.ai if issue persists.

Symptoms:

• Error: "Connection refused" or "Timeout"
• Data not appearing in dashboard
• Connector status shows "Failed"

Solution:

Test connector credentials: Go to Settings > Integrations > Test Connection. Check API rate limits haven't been exceeded. Verify firewall allows outbound connections. Review connector logs: `tail -f /opt/brainpredict/logs/connectors.log`. Re-authenticate connector if OAuth token expired.

Symptoms:

• Stripe payments not updating subscription status
• External system changes not reflected in BrainPredict
• Webhook endpoint returns 404

Solution:

Verify webhook URL is correct in external system (e.g., Stripe Dashboard). Check nginx is routing webhooks correctly: `sudo nginx -t`. Ensure webhook secret matches: Check `.env` file. Test webhook manually: `curl -X POST https://brainpredict.ai/api/v1/stripe/webhook -H "Content-Type: application/json" -d '{}'`. Review webhook logs.

Symptoms:

• Model accuracy dashboard shows low scores
• Predictions don't match expected outcomes
• Model confidence scores are low

Solution:

Check if model has sufficient training data (need 1000+ records minimum). Verify data quality: Check for missing values, outliers, incorrect labels. Retrain model with more data: Go to Platform > AI Models > Retrain. Enable Fast Learning: Settings > AI > Enable Incremental Learning. Wait 3-12 months for accuracy to improve to 95%+.

Symptoms:

• Training stuck at 0% for hours
• Error: "Training timeout"
• High CPU usage during training

Solution:

Check available system resources. Reduce training batch size in config: `TRAINING_BATCH_SIZE=32`. Enable distributed training if multiple servers available. Monitor training logs: `tail -f /opt/brainpredict/logs/training.log`. Consider training during off-peak hours.

Symptoms:

• Error: "Too many connections"
• API requests fail intermittently
• Database becomes unresponsive

Solution:

Increase PostgreSQL max_connections: Edit `/etc/postgresql/*/main/postgresql.conf`, set `max_connections = 200`. Restart PostgreSQL: `sudo systemctl restart postgresql`. Optimize connection pooling in application: Set `DB_POOL_SIZE=20` in `.env`. Close idle connections: `SELECT pg_terminate_backend(pid) FROM pg_stat_activity WHERE state = 'idle';`.

Symptoms:

• Dashboard takes >10 seconds to load
• API response times >5 seconds
• High database CPU usage

Solution:

Identify slow queries: `SELECT * FROM pg_stat_statements ORDER BY total_time DESC LIMIT 10;`. Add missing indexes: Analyze query plans with `EXPLAIN ANALYZE`. Vacuum database: `VACUUM ANALYZE;`. Optimize queries: Use proper JOINs, avoid SELECT *. Consider read replicas for heavy read workloads.

Symptoms:

• Browser shows "Your connection is not private"
• API requests fail with SSL errors
• Certificate warnings in logs

Solution:

Check certificate expiration: `sudo certbot certificates`. Renew certificate: `sudo certbot renew`. Restart nginx: `sudo systemctl restart nginx`. Verify certificate is valid: `openssl s_client -connect brainpredict.ai:443 -servername brainpredict.ai`. Set up auto-renewal: `sudo certbot renew --dry-run`.

Symptoms:

• Unusual login attempts in logs
• Unexpected API calls
• Data access from unknown IPs

Solution:

IMMEDIATELY: Rotate all API keys and secrets. Force logout all users: `python manage.py force-logout-all`. Review access logs: `tail -f /var/log/nginx/access.log`. Block suspicious IPs in firewall. Enable 2FA for all admin accounts. Contact support@brainpredict.ai. Review audit logs for unauthorized changes.