mt5-quant/docs/TROUBLESHOOTING.md

Troubleshooting

Run verify_setup first — it checks all paths and returns actionable hints.

Wine Not Found

macOS

Confirm /Applications/MetaTrader 5.app exists and has been launched at least once.

Check detection:

bash scripts/platform_detect.sh

If using CrossOver, confirm bottle is named MetaTrader5.

Linux

sudo apt install wine64        # Debian/Ubuntu
sudo dnf install wine          # Fedora/RHEL
which wine64                   # confirm on PATH

terminal64.exe Missing

MT5 unpacks terminal64.exe only after first launch.

1. Open MetaTrader 5.app
2. Wait for initialization (~30s)
3. Quit
4. Re-run setup:

bash scripts/setup.sh --yes

MCP Server Not Appearing

Claude Code

claude mcp list                # should show MT5-Quant
claude mcp remove MT5-Quant    # remove stale entry
claude mcp add MT5-Quant -- /absolute/path/to/mt5-quant

Must use absolute path — relative paths break when Claude starts from different directories.

Windsurf

1. Check logs: ~/.windsurf/logs/
2. Verify executable path is absolute
3. Test manually: ./mt5-quant --help

Config Not Found

Set MT5_MCP_HOME or ensure config exists at:

• macOS: ~/.config/mt5-quant/config/mt5-quant.yaml
• Project: config/mt5-quant.yaml

Report Not Found After Backtest

1. Wrong symbol name — brokers use custom names (XAUUSDm, XAUUSD.cent). Check verify_setup or look in <terminal_dir>/history/.

2. No history data — open MT5, open symbol chart, wait for history download.

3. EA crash at startup — check <terminal_dir>/MQL5/Logs/ for OnInit errors.

4. Date range has no trades — try wider range or confirm symbol was active.

MetaEditor Compile Errors

Check <terminal_dir>/MQL5/Logs/:

• Missing #include — copy dependencies into Experts/ alongside .mq5
• Stale .ex5 — delete old binary and recompile

No Deals in Backtest Report

• Use model=0 (every tick) — models 1/2 skip intra-bar movement, producing zero deals for grid/martingale EAs
• Check .set file values appropriate for symbol/broker
• Confirm OnInit() returns INIT_SUCCEEDED (MT5 Journal tab)

Analytics Tools: "No reports in DB" or "Report not found"

Analytics tools load deals from the SQLite database, not from CSV files on disk. Resolution order:

1. report_id (preferred) — ID from list_reports
2. report_dir (legacy) — filesystem path, looks up matching DB entry
3. No args — uses the latest report automatically

Pre-DB reports (before this version) won't be found by report_dir. Re-run the backtest to get a DB-backed report.

deals.csv is no longer written automatically. Call export_deals_csv to generate one on demand:

export_deals_csv()                              # latest report → report_dir/deals.csv
export_deals_csv(report_id: "20260422_…")      # specific report
export_deals_csv(output_path: "/tmp/out.csv")  # custom path

Optimization Never Finishes

# From Claude:
tail_log(job_id=X, filter=errors)
get_optimization_status(job_id=X)

If MT5 crashed, edit <terminal_dir>/terminal.ini and remove line containing OptMode=-1, then retry.

Permission Denied

chmod +x /path/to/mt5-quant

Still Stuck?

1. Run verify_setup and share output
2. Check tail_log for errors
3. Review <terminal_dir>/MQL5/Logs/ for EA errors