Skip to content

Troubleshooting

This guide covers common issues you might encounter with the QuantFin Bot and their solutions. For additional help, check the Logging documentation to analyze system logs.

Common Issues

Connection Problems

Wallet Connection Issues

Problem: Sui wallet won't connect or frequently disconnects

Solutions: 1. Check wallet extension: Ensure Sui wallet extension is installed and updated 2. Browser compatibility: Try different browsers (Chrome, Firefox, Edge) 3. Clear browser cache: Clear cookies and local storage 4. Wallet permissions: Ensure wallet has permission to connect to the site 5. Network issues: Check internet connection stability

Log patterns to look for: 

[ERROR] [wallet] Connection to Sui wallet failed
[WARNING] [wallet] Wallet connection lost, attempting reconnection

Exchange Connection Problems

Problem: Bluefin exchange connection fails or is unstable

Solutions: 1. Check exchange status: Verify Bluefin exchange is operational 2. API limits: Ensure you haven't exceeded API rate limits 3. Network connectivity: Test connection to Bluefin endpoints 4. Firewall settings: Check if firewall is blocking connections

Log patterns to look for: 

[ERROR] [exchange] Connection to Bluefin failed: timeout
[ERROR] [exchange] WebSocket connection lost
[WARNING] [exchange] Rate limit exceeded, backing off

Trading Issues

Orders Not Executing

Problem: Orders are placed but not being filled

Possible causes and solutions:

  1. Insufficient balance
  2. Check wallet balance
  3. Ensure sufficient collateral for leveraged positions

  4. Verify gas fees are available

  5. Price movement

  6. Orders may be out of market range
  7. Adjust spread settings

  8. Use market orders for immediate execution

  9. Order size issues

  10. Check minimum order sizes for the symbol

  11. Ensure order quantity meets exchange requirements

  12. Risk management limits

  13. Position size may exceed wallet exposure limits
  14. Check wallet_exposure_limit_long and wallet_exposure_limit_short

Log patterns to look for: 

[ERROR] [bot] Order placement failed: insufficient balance
[WARNING] [bot] Order rejected: minimum size requirement
[ERROR] [bot] Position size exceeds risk limits

Strategy Not Starting

Problem: Trading strategy fails to start

Solutions: 1. Configuration validation - Check all required parameters are set - Verify parameter values are within valid ranges - Ensure strategy mode is correctly specified

  1. Wallet connection
  2. Confirm wallet is connected and authorized

  3. Check sufficient balance for initial orders

  4. Exchange connectivity

  5. Verify exchange connection is stable
  6. Check API credentials if required

Log patterns to look for: 

[ERROR] [config] Invalid strategy parameter: xgrid_levels must be > 0
[ERROR] [bot] Strategy startup failed: missing required parameters
[WARNING] [bot] Strategy paused due to connection issues

Performance Issues

High Memory Usage

Problem: Bot consuming excessive memory

Solutions: 1. Reduce log levels: Change from DEBUG to INFO in production 2. Clear old data: Remove unnecessary historical data 3. Restart bot: Periodic restarts can help with memory leaks 4. Check data structures: Large position histories can consume memory

Slow Response Times

Problem: API responses are slow or timeout

Solutions: 1. Check system resources: CPU, memory, and disk usage 2. Network latency: Test connection to exchange endpoints 3. Database optimization: Clean up old log files and data 4. Concurrent requests: Reduce number of simultaneous API calls

Configuration Issues

Invalid Strategy Parameters

Problem: Strategy fails due to invalid configuration

Common parameter issues:

  1. Grid levels: Must be positive integers 

    "grid_levels": 3  // Valid
"grid_levels": 0  // Invalid

  2. Take profit distance: Must be positive decimal 

    "tp_distance": 0.0009  // Valid
"tp_distance": -0.001  // Invalid

  3. Wallet exposure: Must be between 0 and 1 

    "wallet_exposure_limit_long": 0.01  // Valid (1%)
"wallet_exposure_limit_long": 1.5   // Invalid (150%)

Missing Required Fields

Problem: Configuration missing required parameters

Required fields by strategy: - Market Making: order_qty, tp_distance - Grid Trading: grid_levels, xgrid_spacing - Dynamic Distribution: wallet_exposure_limit_long, wallet_exposure_limit_short

Data Issues

Missing Historical Data

Problem: Charts or analytics show no data

Solutions: 1. Check data files: Verify equity_history.json exists and is readable 2. Date range: Ensure requested date range contains data 3. User permissions: Verify user has access to their data 4. Data corruption: Check for JSON parsing errors in logs

Backup and Recovery

Problem: Data loss or corruption

Solutions: 1. Automatic backups: System creates hourly backups automatically 2. Manual restore: Restore from backup files in backups/ directory 3. Data validation: Use built-in data validation tools 4. Fresh start: Reset user data if corruption is extensive

API Issues

Authentication Failures

Problem: API calls return 401 Unauthorized

Solutions: 1. Check API keys: Verify API tokens are valid and not expired 2. Request headers: Ensure Authorization header is properly formatted 3. Token refresh: Regenerate API tokens if needed 4. Rate limiting: Check if too many requests are being made

Rate Limiting

Problem: API calls return 429 Too Many Requests

Solutions: 1. Reduce request frequency: Implement exponential backoff 2. Batch requests: Combine multiple operations where possible 3. Optimize polling: Reduce frequency of status checks 4. Cache responses: Cache frequently accessed data

System Issues

High CPU Usage

Problem: Bot consuming too much CPU

Solutions: 1. Optimize strategies: Reduce calculation complexity 2. Increase polling intervals: Less frequent market data updates 3. Profile code: Identify performance bottlenecks 4. Hardware upgrade: Consider more powerful hardware

Disk Space Issues

Problem: Running out of disk space

Solutions: 1. Log rotation: Ensure log files are being rotated properly 2. Clean old backups: Remove old backup files 3. Data archival: Archive old trading data 4. Monitoring: Set up disk space monitoring

Error Codes

Common Error Codes

Code Description Solution
E001 Wallet connection failed Check wallet extension and permissions
E002 Insufficient balance Add funds or reduce position size
E003 Invalid strategy parameter Check configuration values
E004 Exchange connection timeout Check network and exchange status
E005 Order placement failed Verify balance and order parameters
E006 Rate limit exceeded Reduce API call frequency
E007 Data corruption detected Restore from backup
E008 Authentication failed Check API keys and tokens

Diagnostic Tools

Health Check

Use the health check endpoint to verify system status: 

curl -X GET "https://quantfin.dexalgo.org/api/health"

System Metrics

Monitor system performance: 

curl -X GET "https://quantfin.dexalgo.org/api/metrics"

Log Analysis

Use these commands to analyze logs: 

# Check for recent errors
grep -E "(ERROR|CRITICAL)" bot.log | tail -20

# Monitor trading activity
grep -E "(Order|Position|Trade)" bot.log | tail -50

# Check specific user activity
grep "user123" bot.log | tail -30

Getting Help

Before Contacting Support

  1. Check logs: Review error logs for specific error messages
  2. Verify configuration: Ensure all parameters are correct
  3. Test connectivity: Verify wallet and exchange connections
  4. Try basic solutions: Restart bot, clear cache, check balance

Information to Include

When reporting issues, include: - Error messages from logs - Configuration details (redact sensitive info) - Steps to reproduce the issue - System environment (browser, OS) - Timestamp of when issue occurred

Support Channels

  • GitHub Issues: Technical problems and bug reports
  • Documentation: Check this guide and API reference
  • Community: Discord or Telegram channels (if available)

Prevention Tips

Best Practices

  1. Regular monitoring: Check logs and performance regularly
  2. Keep updated: Update bot and dependencies regularly
  3. Test configurations: Validate settings before live trading
  4. Backup data: Ensure backups are working properly
  5. Monitor resources: Keep track of system resource usage

Safety Measures

  1. Start small: Test with small position sizes initially
  2. Use stop losses: Configure appropriate risk management
  3. Monitor markets: Be aware of market conditions
  4. Have emergency plan: Know how to quickly stop trading

For more detailed system monitoring, see the Logging documentation.