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.
Long paths and network folders
Beta.41 improves Windows long-path handling and completed-file publication on NFS and NTFS mounts. If saving still fails, check that the destination is mounted, writable, and has enough free space. A long individual filename can still exceed the filesystem’s limit even when the full path is supported; try a shorter filename or save folder.
Motrix normalizes unsupported filename characters and chooses another name when normalization would collide with an existing file. Check the task’s final filename before opening it from another application. Keep partial files and recovery data while investigating a failed save.
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. An Unknown NAT type is inconclusive. Follow the guide to check upstream routers and ISP restrictions.
- 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) |
| Download list and task history | <userData>/motrix.db |
| Download recovery data | aria2.db in the engine config dir by default; change it with Settings → Advanced → Progress and recovery → Recovery data file |
| 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.