nofx/docs/guides/TROUBLESHOOTING.md

🔧 Troubleshooting Guide

This guide helps you diagnose and fix common issues before submitting a bug report.

---

📋 Quick Diagnostic Checklist

Before reporting a bug, please check:

1. ✅ Backend is running: docker compose ps or ps aux | grep nofx
2. ✅ Frontend is accessible: Open http://localhost:3000 in browser
3. ✅ API is responding: curl http://localhost:8080/api/health
4. ✅ Check logs for errors: See How to Capture Logs below

---

🐛 Common Issues & Solutions

1. Trading Issues

❌ Only Opening Short Positions (Issue #202)

Symptom: AI only opens short positions, never long positions, even when market is bullish.

Root Cause: Binance account is in One-way Mode instead of Hedge Mode.

Solution:

1. Login to Binance Futures
2. Click ⚙️ Preferences (top right)
3. Select Position Mode
4. Switch to Hedge Mode (双向持仓)
5. ⚠️ Important: Close all positions before switching

Why this happens:

• Code uses PositionSide(LONG) and PositionSide(SHORT) parameters
• These only work in Hedge Mode
• In One-way Mode, orders fail or only one direction works

For Subaccounts:

• Some Binance subaccounts may not have permission to change position mode
• Use main account or contact Binance support to enable this permission

---

❌ Order Error: code=-4061 Position Side Mismatch

Error Message: Order's position side does not match user's setting

Solution: Same as above - switch to Hedge Mode.

---

❌ Leverage Error: Subaccounts restricted to 5x leverage

Symptom: Orders fail with leverage error when trying to use >5x leverage.

Solution:

1. Open Web UI → Trader Settings
2. Set leverage to 5x or lower:

   {
     "btc_eth_leverage": 5,
     "altcoin_leverage": 5
   }
   

3. Or use main account (supports up to 50x BTC/ETH, 20x altcoins)

---

❌ Positions Not Executing

Check these:

1. API Permissions:

   • Go to Binance → API Management
   • Verify "Enable Futures" is checked
   • Check IP whitelist (if enabled)

2. Account Balance:

   • Ensure sufficient USDT in Futures wallet
   • Check margin usage is not at 100%

3. Symbol Status:

   • Verify trading pair is active on exchange
   • Check if symbol is in maintenance mode

4. Decision Logs:

   # Check latest decision
   ls -lt decision_logs/your_trader_id/ | head -5
   cat decision_logs/your_trader_id/latest_file.json
   

   • Look for AI decision: was it "wait", "hold", or actual trade?
   • Check if position_size_usd is within limits

---

2. AI Decision Issues

❌ AI Always Says "Wait" / "Hold"

Possible Causes:

1. Market Conditions: AI may genuinely see no good opportunities
2. Risk Limits: Account equity too low, margin usage too high
3. Historical Performance: AI being cautious after losses

How to Check:

# View latest decision reasoning
cat decision_logs/your_trader_id/$(ls -t decision_logs/your_trader_id/ | head -1)

Look at the AI's Chain-of-Thought reasoning section.

Solutions:

• Wait for better market conditions
• Check if all candidate coins have low liquidity
• Verify use_default_coins: true or coin pool API is working

---

❌ AI Making Bad Decisions

Remember: AI trading is experimental and not guaranteed to be profitable.

Things to Check:

1. Decision Interval: Is it too short? (Recommended: 3-5 minutes)
2. Leverage Settings: Too aggressive?
3. Historical Feedback: Check performance logs to see if AI is learning
4. Market Volatility: High volatility = higher risk

Adjustments:

• Reduce leverage for more conservative trading
• Increase decision interval to reduce over-trading
• Use smaller initial balance for testing

---

3. Connection & API Issues

❌ Backend Won't Start

Error: port 8080 already in use

Solution:

# Find what's using the port
lsof -i :8080
# OR
netstat -tulpn | grep 8080

# Kill the process or change port in .env
NOFX_BACKEND_PORT=8081

---

❌ Frontend Can't Connect to Backend

Symptoms:

• UI shows "Loading..." forever
• Browser console shows 404 or network errors

Solutions:

1. Check backend is running:

   docker compose ps  # Should show backend as "Up"
   # OR
   curl http://localhost:8080/api/health  # Should return {"status":"ok"}
   

2. Check port configuration:

   • Backend default: 8080
   • Frontend default: 3000
   • Verify .env settings match

3. CORS Issues:

   • If running frontend and backend on different ports/domains
   • Check browser console for CORS errors
   • Backend should allow frontend origin

---

❌ Exchange API Errors

Error: invalid signature / timestamp errors

Solutions:

1. Check System Time:

   date  # Should be accurate
   # If wrong, sync with NTP:
   sudo ntpdate -s time.nist.gov
   

2. Verify API Keys:

   • Not expired
   • Have correct permissions (Futures enabled)
   • IP whitelist includes your server IP

3. Rate Limits:

   • Binance has strict rate limits
   • Reduce number of traders or decision frequency

---

4. Frontend Issues

❌ UI Not Updating / Showing Old Data

Solutions:

1. Hard Refresh:

   • Chrome/Firefox: Ctrl+Shift+R (Windows/Linux) or Cmd+Shift+R (Mac)
   • Safari: Cmd+Option+R

2. Clear Browser Cache:

   • Settings → Privacy → Clear browsing data
   • Or open in Incognito/Private mode

3. Check SWR Polling:

   • Frontend uses SWR with 5-10s intervals
   • Data should auto-refresh
   • Check browser console for fetch errors

---

❌ Charts Not Rendering

Possible Causes:

1. No historical data yet (system just started)
2. JavaScript errors in console
3. Browser compatibility issues

Solutions:

• Wait 5-10 minutes for data to accumulate
• Check browser console (F12) for errors
• Try different browser (Chrome recommended)
• Ensure backend API endpoints are returning data

---

5. Database Issues

❌ database is locked Error

Cause: SQLite database being accessed by multiple processes.

Solution:

# Stop all NOFX processes
docker compose down
# OR
pkill nofx

# Restart
docker compose up -d
# OR
./nofx

---

❌ Trader Configuration Not Saving

Check:

1. Permissions:

   ls -l config.db trading.db
   # Should be writable by current user
   

2. Disk Space:

   df -h  # Ensure disk not full
   

3. Database Integrity:

   sqlite3 config.db "PRAGMA integrity_check;"
   

---

📊 How to Capture Logs

Backend Logs

Docker:

# View last 100 lines
docker compose logs backend --tail=100

# Follow live logs
docker compose logs -f backend

# Save to file
docker compose logs backend --tail=500 > backend_logs.txt

Manual/PM2:

# Terminal where you ran ./nofx shows logs

# PM2:
pm2 logs nofx --lines 100

# Save to file
pm2 logs nofx --lines 500 > backend_logs.txt

---

Frontend Logs (Browser Console)

1. Open DevTools:

   • Press F12 or Right-click → Inspect

2. Console Tab:

   • See JavaScript errors and warnings
   • Look for red error messages

3. Network Tab:

   • Filter by "XHR" or "Fetch"
   • Look for failed requests (red status codes)
   • Click on failed request → Preview/Response to see error details

4. Capture Screenshot:

   • Windows: Win+Shift+S
   • Mac: Cmd+Shift+4
   • Or use browser DevTools screenshot feature

---

Decision Logs (Trading Issues)

# List recent decision logs
ls -lt decision_logs/your_trader_id/ | head -10

# View latest decision
cat decision_logs/your_trader_id/$(ls -t decision_logs/your_trader_id/ | head -1) | jq .

# Search for specific symbol
grep -r "BTCUSDT" decision_logs/your_trader_id/

# Find decisions that resulted in trades
grep -r '"action": "open_' decision_logs/your_trader_id/

What to look for in decision logs:

• chain_of_thought: AI's reasoning process
• user_prompt: Market data AI received
• decision: Final decision (action, symbol, leverage, etc.)
• account_state: Account balance, margin, positions at decision time
• execution_result: Whether trade succeeded or failed

---

🔍 Diagnostic Commands

System Health Check

# Backend health
curl http://localhost:8080/api/health

# List all traders
curl http://localhost:8080/api/traders

# Check specific trader status
curl http://localhost:8080/api/status?trader_id=your_trader_id

# Get account info
curl http://localhost:8080/api/account?trader_id=your_trader_id

Docker Status

# Check all containers
docker compose ps

# Check resource usage
docker stats

# Restart specific service
docker compose restart backend
docker compose restart frontend

Database Queries

# Check traders in database
sqlite3 config.db "SELECT id, name, ai_model_id, exchange_id, is_running FROM traders;"

# Check AI models
sqlite3 config.db "SELECT id, name, model_type, enabled FROM ai_models;"

# Check system config
sqlite3 config.db "SELECT key, value FROM system_config;"

---

📝 Still Having Issues?

If you've tried all the above and still have problems:

1. Gather Information:

   • Backend logs (last 100 lines)
   • Frontend console screenshot
   • Decision logs (if trading issue)
   • Your environment details

2. Submit Bug Report:

   • Use the Bug Report Template
   • Include all logs and screenshots
   • Describe what you've already tried

3. Join Community:

   • Telegram Developer Community
   • GitHub Discussions

---

🆘 Emergency: System Completely Broken

Complete Reset (⚠️ Will lose trading history):

# Stop everything
docker compose down

# Backup databases (just in case)
cp config.db config.db.backup
cp trading.db trading.db.backup

# Remove databases (fresh start)
rm config.db trading.db

# Restart
docker compose up -d --build

# Reconfigure through web UI
open http://localhost:3000

Partial Reset (Keep configuration, clear logs):

# Clear decision logs
rm -rf decision_logs/*

# Clear Docker cache and rebuild
docker compose down
docker compose build --no-cache
docker compose up -d

---

📚 Additional Resources

• FAQ - Frequently Asked Questions
• Getting Started - Setup guide
• Architecture Docs - How the system works
• CLAUDE.md - Developer documentation

---

Last Updated: 2025-11-02