crypto_trader/docs/user_manual/troubleshooting.md

Troubleshooting Guide

Common issues and solutions for Crypto Trader.

Application Won't Start

Issue: Backend server won't start

Solutions:

1. Check Python version (requires 3.11+)
2. Verify all dependencies are installed: pip install -r requirements.txt && pip install -r backend/requirements.txt
3. Check if port 8000 is already in use: lsof -i :8000 (Linux/macOS) or netstat -ano | findstr :8000 (Windows)
4. Try running manually: python -m uvicorn backend.main:app --reload --port 8000
5. Check log files in ~/.local/share/crypto_trader/logs/
6. Verify database permissions

Issue: Frontend won't start

Solutions:

1. Verify Node.js is installed (v18+): node --version
2. Install dependencies: cd frontend && npm install
3. Check if port 3000 is already in use
4. Try running manually: cd frontend && npm run dev
5. Clear node_modules and reinstall: rm -rf node_modules package-lock.json && npm install
6. Check browser console for errors

Issue: Cannot connect to backend from frontend

Solutions:

1. Verify backend is running on http://localhost:8000
2. Check API endpoint in browser: http://localhost:8000/docs
3. Check CORS settings in backend
4. Verify API client URL in frontend code
5. Check browser console for CORS errors
6. Verify firewall isn't blocking connections

Issue: Import errors

Solutions:

1. Reinstall dependencies: pip install -r requirements.txt
2. Verify virtual environment is activated
3. Check Python path configuration
4. Reinstall problematic packages

Exchange Connection Issues

Issue: Cannot connect to exchange

Solutions:

1. Verify API keys are correct
2. Check API key permissions
3. Verify internet connection
4. Check exchange status (may be down)
5. Review exchange rate limits
6. Check firewall settings

Issue: API key errors

Solutions:

1. Verify API keys are valid
2. Check key permissions (read-only vs trading)
3. Regenerate API keys if needed
4. Verify IP whitelist settings
5. Check key expiration dates

Trading Issues

Issue: Orders not executing

Solutions:

1. Check account balance
2. Verify API permissions include trading
3. Check order parameters (price, quantity)
4. Review exchange order limits
5. Check if market is open
6. Verify order type is supported

Issue: Positions not updating

Solutions:

1. Refresh portfolio view
2. Check database connection
3. Verify exchange connection
4. Review application logs
5. Restart application

Data Issues

Issue: Missing historical data

Solutions:

1. Check data collection is enabled
2. Verify exchange connection
3. Check data storage permissions
4. Review data retention settings
5. Manually trigger data collection

Issue: Incorrect price data

Solutions:

1. Verify exchange connection
2. Check data source
3. Review data quality settings
4. Clear and reload data
5. Check for data gaps

Performance Issues

Issue: Application is slow

Solutions:

1. Check system resources (CPU, memory)
2. Reduce historical data retention
3. Optimize database (VACUUM ANALYZE)
4. Close unnecessary strategies
5. Reduce chart data points
6. Check for memory leaks in logs

Issue: High memory usage

Solutions:

1. Reduce data retention period
2. Limit number of active strategies
3. Reduce chart history
4. Clear old logs
5. Restart application periodically

Database Issues

Issue: Database errors

Solutions:

1. Check database connection to PostgreSQL
2. Verify disk space available
3. Check database user permissions
4. Backup and restore database if corrupted
5. Review database logs

Issue: Database connection failed

Solutions:

1. Check if PostgreSQL service is running
2. Verify connection URL in config.yaml
3. Check network connectivity to database host
4. Verify database user credentials and permissions
5. Check PostgreSQL logs

Configuration Issues

Issue: Settings not saving

Solutions:

1. Check config directory permissions
2. Verify config file is writable
3. Check disk space
4. Review application logs
5. Manually edit config file if needed

Issue: Configuration errors

Solutions:

1. Validate YAML syntax
2. Check for invalid values
3. Review default configuration
4. Reset to defaults if needed
5. Check configuration file encoding

Web UI Issues

Issue: Page not loading or blank screen

Solutions:

1. Check browser console for JavaScript errors (F12)
2. Clear browser cache and reload
3. Verify frontend server is running
4. Check network tab for failed API requests
5. Try a different browser
6. Check if backend is accessible

Issue: WebSocket connection not working

Solutions:

1. Check WebSocket status indicator in Dashboard
2. Verify backend WebSocket endpoint is accessible
3. Check browser console for WebSocket errors
4. Verify firewall/proxy settings allow WebSocket connections
5. Try refreshing the page
6. Check backend logs for WebSocket errors

Issue: Real-time updates not appearing

Solutions:

1. Check WebSocket connection status
2. Verify WebSocket is connected (green indicator)
3. Refresh the page
4. Check browser console for errors
5. Verify backend is sending WebSocket messages
6. Check network tab for WebSocket connection

Issue: Forms not submitting

Solutions:

1. Check browser console for validation errors
2. Verify all required fields are filled
3. Check for error messages in the form
4. Verify API endpoint is accessible
5. Check network tab for failed requests
6. Look for Snackbar error notifications

Strategy Issues

Issue: Strategy not generating signals

Solutions:

1. Verify strategy is enabled (check Strategies page)
2. Check strategy parameters
3. Verify data is available
4. Check strategy logs
5. Review signal generation logic
6. Check Operations Panel for running strategies

Issue: Strategy errors

Solutions:

1. Check strategy parameters in Strategy Management page
2. Verify data availability
3. Review strategy code
4. Check application logs
5. Test with different parameters
6. Check error notifications in UI

Getting Help

If you continue to experience issues:

1. Check Logs: Review application logs in ~/.local/share/crypto_trader/logs/
2. Review Documentation: Check user manual and API docs
3. Check FAQ: See FAQ for common questions
4. Report Issues: Create an issue with:
   • Error messages
   • Steps to reproduce
   • System information
   • Log files

Log Files

Log files are located in ~/.local/share/crypto_trader/logs/:

• app.log: Main application log
• trading.log: Trading operations
• errors.log: Error messages
• debug.log: Debug information (if enabled)

Review logs for detailed error information.