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](faq.md) 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.