rTorrent Trouble-Shooting Guide

This page describes common symptoms and their remedies.

rTorrent emits a certain log or error message

Tracker: [Couldn't connect to server]

Well, that's basically what the message says, reasons include:

• the domain in the announce URL resolves to the wrong IP (wait 24 hours, then check again).

• there is a routing problem somewhere between you and the server in the announce URL (try to tracepath or traceroute its domain).

If the problem persists, try to contact someone that is responsible for the tracker in question.

Timeout was reached / Timed out

Although you could connect to the tracker, it is overloaded or doesn't answer for other reasons.

Could not parse bencoded data / Server returned nothing

The response from the server is malformed or empty. Usually this means the server is overloaded and returned a 500 error page (which is not a proper response for a torrent announce).

Messages containing "not registered", "torrent cannot be found", or "unregistered"

The info hash of the torrent you're trying to announce is not known to the tracker, i.e. usually it got deleted from the tracker's database some time after you've downloaded it.

Hash check on download completion found bad chunks

This message can indicate trouble with either your hard disk or your main memory, especially when it occurs on random chunks, when you repeatedly hash the same torrent. So do just that to check for this, cycle through ^K ^R repeatedly, and take note of the failing chunks. If they're constant, start the item and get them from the source, otherwise it's likely a hardware problem.

Run memtest to check your memory, and/or an appropriate disk checking tool (S.M.A.R.T., fschk). Also make sure the file system and kernel you use can cope with rTorrent's intensive use of mmap().

rTorrent doesn't behave as expected

Some torrents persistently refuse to be started

Sometimes torrents added to rTorrent will stay paused in the client, and they also cannot be started manually by ^S. This is usually due to people uploading metafiles created by ruTorrent with the "Add fast resume" option active. This causes problems for all downloaders that use rTorrent, since their client doesn't have the data that the libtorrent_resume field promises to be there, and thus gets confused and stubborn.

To remove the offending information, there are three ways:

1. do a ^K ^R ^S cycle in the ncurses UI.

2. Apply chtor --clean-rtorrent to the .torrent file, then reload it.

3. If you use FlexGet, use the torrent_scrub plugin.

The other common cause is you have the pretty much useless¹ close_untied schedule in your configuration.

rTorrent crashes

TODO

How to diagnose a problem's root cause

Creating a log of external script output and results

Add the following line to your configuration, or paste it into a ^X command prompt:

• log.execute = /var/torrent/logs/execute.log

Of course, the path has to fit your system. The resulting output looks like this:

• ---
  chmod g+w ./.scgi_local
  ---
  
  --- Success ---

Working with gdb in case of a crash

TODO Explain how to compile with debug symbols...

To run rTorrent under gdb (GNU debugger) control, use this:

• cd ~/rtorrent
  gdb --args rtorrent -n -o import=$PWD/rtorrent.rc

Note that this shows how to handle additional arguments given to rTorrent, in this case loading a config file at a non-standard location.

On the gdb prompt, enter these commands:

• handle SIGPIPE ignore
  handle SIGPIPE nostop
  handle SIGPIPE noprint
  handle SIGUSR1 nostop
  handle SIGUSR1 ignore
  handle SIGUSR1 noprint
  run

Then wait for the crash and enter bt (backtrace) to show a stack dump.

How to report problems in a rTorrent ticket, or on IRC

On a general note, read ESR's excellent summary of the topic and also How to Report Bugs Effectively.

TL;DR: «doesn't work» or similar is useless as a problem report, don't expect any answer.

Especially:

• Check the rest of this page, the rTorrent bug tracker (on github, old tickets are in Trac), and for that matter Google before you nag people with well-known and solved problems.

• On IRC, do NOT wait for someone to answer questions like Can someone help? and the like. Instead, state your problem, and WAIT; many people are busy or idle, eventually someone will notice you (in the backlog).

• If your problem is with ruTorrent, go to ##rutorrent on freenode.net.

• If you can't be bothered to describe your problem upfront, then don't expect people to spend time on dragging it out of you.

Specific to rTorrent, here's what you need to provide if you expect even the slightest chance of getting some targeted help:

• State versions (& type) of your OS, rTorrent and possibly ruTorrent or other add-ons you run.

• How did you install? — using packages, via installer script (which one‽), from source, from bleeding-edge source, etc.

• Fresh install? Or it "suddenly stopped working", and what did you do to cause that?

• Provide exact error messages, not your transcription of them, use https://pastee.org/ to show your ~/.rtorrent.rc.

• Provide screen shots if that helps.

---