Troubleshooting
Work top-down: check the engine first, then the individual task, then the network. Most problems resolve in the first two steps.
Step 1 — Check the engine
Motrix drives a bundled download engine (aria2). If the engine is unhappy, nothing downloads. The stats bar shows its state at all times: Engine ready, Engine starting, or Engine offline.
If it’s offline — or downloads mysteriously refuse to start — open the Dashboard’s Engine tile and click Diagnose. The diagnostics dialog runs five checks: Bundled aria2, Engine Features, Motrix RPC port, Process ownership, and Engine communication — then recommends a fix:
- Restart engine — the general cure for a wedged engine.
- Force stop & recover — when a leftover aria2 process from a previous run is squatting on Motrix’s port. Motrix verifies the process is really its own before offering to stop it.
- Restore Motrix default port — when the port conflict has cleared and you want to return from a fallback port.
Tip
Firewalls and antivirus tools sometimes block the engine’s local RPC connection. If diagnostics repeatedly fail at Engine communication, add Motrix to your security software’s allow list.
Step 2 — Read the task’s error
A failed task tells you why, in words — select it and read the reason and hint:
| Reason | What to do |
|---|---|
| Disk is full | Free up disk space or change the save folder, then retry |
| Could not write the file | Check folder permissions and available disk space |
| Authorization required | Check your credentials — for browser-bound files, paste a fresh cURL command (Adding tasks) |
| Network connection failed / Download timed out | Check your connection, then retry |
| Too many redirects | The source link is likely broken; get a fresh link |
| File checksum did not match | The file may be corrupted — re-download to verify |
| File not found / Server returned an error | The problem is on the server’s side |
| Torrent metadata could not be fetched | Check the magnet link or add more trackers, then retry |
| Tracker connection failed | See the slow-torrent checklist below |
Retry re-runs the task; Alt+Click on Retry lets you fix options first.
Slow torrent checklist
Work through these in order — each step is the fix for a different bottleneck:
- Open the Peers tab. No peers at all? The problem is connectivity or the swarm, not bandwidth.
- Check the seeder count. A torrent with one seeder will never be fast; that’s the swarm, not Motrix.
- Sync trackers. On the task’s Trackers tab hit Sync; check the Trackers page shows healthy entries.
- Fix your reachability. Enable port mapping and run the NAT tile’s diagnostic. Symmetric NAT or a mismatched external IP means CGNAT — expect fewer inbound peers.
- Check the Speed Limit tile. If it shows an active reason (Schedule, Low-speed mode, Bandwidth reserve), that’s your “slowness”.
- Confirm DHT is on (Settings → BitTorrent) — magnet links especially depend on it.
Where Motrix keeps its files
<userData> is ~/Library/Application Support/Motrix on macOS, %APPDATA%\Motrix on Windows, and ~/.config/Motrix on Linux.
| Data | Location |
|---|---|
| Settings | <userData>/settings.json |
| Log file | <userData>/logs/motrix.log (rotates at 5 MB to motrix.log.1) |
| Task history / session (SQLite) | aria2.db in the engine config dir (path configurable in Settings → Advanced) |
| Torrent metadata | <userData>/torrents/ |
| Plugins | <userData>/plugins/ |
| GeoIP database | <userData>/geoip/GeoLite2-Country.mmdb |
| Media temp files | motrix-media in the OS temp dir (cleanable via Settings → Integration → Media tools) |
Reporting a bug
Help → Report an Issue opens the issue tracker. Include your Motrix version (Settings → About), your OS, and the log file from the table above — that combination answers most first questions up front.