Sonarr/Sonarr · error · DownloadClientException

rTorrent returned error code {fault.FaultCode}: {fault.Fault

Error message

rTorrent returned error code {fault.FaultCode}: {fault.FaultString}

What it means

RTorrentProxy.ExecuteRequest throws DownloadClientException when the XML-RPC response document contains a <fault> element. It parses the fault into an RTorrentFault and surfaces both FaultCode and FaultString. An XML-RPC fault means rTorrent itself reported the method call failed (bad method name, wrong argument types/count, internal rTorrent error). This is the lowest-level rTorrent error in the proxy and is the root cause for many of the higher-level add/label/remove failures.

Source

Thrown at src/NzbDrone.Core/Download/Clients/rTorrent/RTorrentProxy.cs:212

            if (!settings.Username.IsNullOrWhiteSpace())
            {
                requestBuilder.NetworkCredential = new NetworkCredential(settings.Username, settings.Password);
            }

            var request = requestBuilder.Call(methodName, args).Build();

            var response = _httpClient.Execute(request);

            var doc = XDocument.Parse(response.Content);

            var faultElement = doc.XPathSelectElement("./methodResponse/fault");

            if (faultElement != null)
            {
                var fault = new RTorrentFault(faultElement);

                throw new DownloadClientException($"rTorrent returned error code {fault.FaultCode}: {fault.FaultString}");
            }

            return doc;
        }
    }
}

View on GitHub (pinned to da2284d7ea)

Solutions

1. Read the FaultCode and FaultString in the message — they identify the exact rTorrent-side rejection.
2. Match the XML-RPC method names/arity to the installed rTorrent version's documentation.
3. Ensure referenced hashes exist (use HasHashTorrent) before d.* commands.
4. Check rtorrent.rc / plugins for command definitions the code assumes exist.

Example fix

// before: calling a method the rTorrent build doesn't expose -> fault
var response = ExecuteRequest(settings, "load.start", args.ToArray());  // fault: unknown method

// after: branch on rTorrent capability / version, or use the supported command
var method = SupportsLoadStart(settings) ? "load.start" : "load.normal";
var response = ExecuteRequest(settings, method, args.ToArray());

// Probe a cheap method to confirm XML-RPC/scgi connectivity and version before heavy ops:
try { var v = _proxy.ExecuteRequest(settings, "system.client_version").GetStringResponse(); }
catch (DownloadClientException ex) { _logger.Warn(ex, "rTorrent XML-RPC probe failed; check scgi/route."); }

static bool IsXmlRpcFault(DownloadClientException ex) =>
    ex.Message.Contains("rTorrent returned error code", StringComparison.OrdinalIgnoreCase);

try { return _proxy.ExecuteRequest(settings, method, args); }
catch (DownloadClientException ex) when (IsXmlRpcFault(ex))
{
    _logger.Error(ex, "rTorrent XML-RPC fault on '{0}'; check method name/arity/version.", method);
    throw;
}

When it happens

Trigger: Any ExecuteRequest where _httpClient.Execute returns content whose parsed XDocument has ./methodResponse/fault. Triggered by unknown XML-RPC method names, argument arity mismatches, type errors, or rTorrent internal failures (e.g. referencing a torrent hash that does not exist with d.* commands).

Common situations: rTorrent version mismatch (method renamed/removed, e.g. load.start vs load.normal across versions); wrong number of args to a d.* command; scgi payload type error; referring to a hash not present in the session; rTorrent plugin/config invoking undefined commands.

Related errors

• Could not add torrent: {0}.
• Could not set label to {1} for torrent: {0}.
• Could not push unique view {0} for torrent: {1}.
• Could not remove torrent: {0}.
• Downloading torrent failed

AI-assisted analysis of Sonarr/Sonarr@da2284d7ea (2026-08-13). Data as JSON: /api/errors/e492c4434957d1fc. Report an issue: GitHub.