Sonarr/Sonarr · error · DownloadClientException

Failed to connect to qBittorrent, please check your settings

Error message

Failed to connect to qBittorrent, please check your settings.

What it means

Thrown by QBittorrentProxyV2.ProcessRequest when API key authentication is in use and a non-HttpException error occurs during request execution. This is the catch-all for unexpected errors — raw socket exceptions, TLS handshake failures not wrapped as HttpException, timeouts, or other runtime errors.

Source

Thrown at src/NzbDrone.Core/Download/Clients/QBittorrent/QBittorrentProxyV2.cs:402

                try
                {
                    return _httpClient.Execute(requestWithApiKey).Content;
                }
                catch (HttpException ex)
                {
                    if (ex.Response.StatusCode is HttpStatusCode.Unauthorized or HttpStatusCode.Forbidden)
                    {
                        _logger.Debug(ex, "qbitTorrent authentication failed.");

                        throw new DownloadClientAuthenticationException("Failed to authenticate with qBittorrent.", ex);
                    }

                    throw new DownloadClientException("Failed to connect to qBittorrent, check your settings.", ex);
                }
                catch (Exception ex)
                {
                    throw new DownloadClientException("Failed to connect to qBittorrent, please check your settings.", ex);
                }
            }

            AuthenticateClient(requestBuilder, settings);

            var request = requestBuilder.Build();
            request.LogResponseContent = true;
            request.SuppressHttpErrorStatusCodes = [HttpStatusCode.Forbidden];

            try
            {
                var response = _httpClient.Execute(request);

                if (response.StatusCode == HttpStatusCode.Forbidden)
                {
                    _logger.Debug("Authentication required, logging in.");

                    AuthenticateClient(requestBuilder, settings, true);

View on GitHub (pinned to da2284d7ea)

Solutions

Inspect the inner Exception's type and message for the specific failure.
Verify network connectivity and stability to qBittorrent.
Check application logs for the full stack trace.
If TLS-related, verify certificate configuration and system trust store.

Defensive patterns

Strategy: try-catch

Validate before calling

// Pre-flight network check to catch transport issues early
using (var tcpClient = new TcpClient())
{
    await tcpClient.ConnectAsync(settings.Host, settings.Port);
}

Type guard

static bool IsNonHttpException(DownloadClientException ex) =>
    ex.InnerException is not HttpException && ex.InnerException is not WebException;

Try / catch

try
{
    proxy.GetTorrents(settings);
}
catch (DownloadClientException ex) when (ex.InnerException is not HttpException)
{
    _logger.Error(ex.InnerException, "Unexpected non-HTTP error contacting qBittorrent with API key");
    throw;
}

Prevention

Log the full inner exception type and message for diagnosis.
Perform a pre-flight connectivity check to catch transport issues early.
Monitor for TLS/socket errors that may indicate network configuration problems.
Review the application's HTTP client configuration (timeouts, TLS settings).

When it happens

Trigger: Any Exception (not HttpException) thrown by _httpClient.Execute when settings.ApiKey is set — socket-level error, TLS exception, operation timeout, or unexpected runtime error.

Common situations: Network timeout; socket exception from a dropped connection; TLS/SSL handshake error; DNS resolution failure; unexpected null reference or serialization error in the HTTP layer.

Related errors

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