Sonarr/Sonarr · error · DownloadClientException

Failed to connect to qBittorrent. Check your settings and qB

Error message

Failed to connect to qBittorrent. Check your settings and qBittorrent configuration.

What it means

Thrown by QBittorrentProxyV2.IsApiSupported when the v2 API support probe (GET /api/v2/app/webapiVersion) returns 401 Unauthorized. This means qBittorrent requires authentication even for this unauthenticated probe, which occurs when 'Bypass authentication for clients on localhost' is disabled and no API key or credentials are configured.

Source

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

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

                // Version request will return 404 if it doesn't exist.
                if (response.StatusCode == HttpStatusCode.NotFound)
                {
                    return false;
                }

                if (response.StatusCode == HttpStatusCode.Forbidden)
                {
                    return true;
                }

                if (response.StatusCode == HttpStatusCode.Unauthorized)
                {
                    throw new DownloadClientException("Failed to connect to qBittorrent. Check your settings and qBittorrent configuration.", new HttpException(response));
                }

                if (response.HasHttpError)
                {
                    throw new DownloadClientException("Failed to connect to qBittorrent, check your settings.", new HttpException(response));
                }

                return true;
            }
            catch (WebException ex)
            {
                if (ex.Status == WebExceptionStatus.TrustFailure)
                {
                    throw new DownloadClientUnavailableException("Unable to connect to qBittorrent, certificate validation failed.", ex);
                }

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

View on GitHub (pinned to da2284d7ea)

Solutions

Set username and password (or API key) in the qBittorrent download client settings.
Alternatively, enable 'Bypass authentication for clients on localhost' in qBittorrent WebUI options if the application runs on the same host.
Verify qBittorrent's WebUI authentication settings (Options > Web UI).
Test accessing the qBittorrent WebUI URL in a browser to confirm auth requirements.

Defensive patterns

Strategy: validation

Validate before calling

// Ensure credentials or API key are configured before API detection
if (settings.ApiKey.IsNullOrWhiteSpace() &&
    (settings.Username.IsNullOrWhiteSpace() || settings.Password.IsNullOrWhiteSpace()))
{
    throw new DownloadClientAuthenticationException(
        "qBittorrent requires authentication. Set username/password or API key in settings.");
}

Type guard

static bool IsApiDetectionAuthFailure(DownloadClientException ex) =>
    ex.InnerException is HttpException http && http.Response.StatusCode == HttpStatusCode.Unauthorized;

Try / catch

try
{
    var supported = proxyV2.IsApiSupported(settings);
}
catch (DownloadClientException ex) when (ex.InnerException is HttpException { Response.StatusCode: HttpStatusCode.Unauthorized })
{
    _logger.Error("qBittorrent requires authentication for API access. Configure credentials or API key.");
    throw;
}

Prevention

Always configure credentials or an API key for qBittorrent, even for local installations.
Enable 'Bypass authentication for clients on localhost' in qBittorrent only for local deployments.
Test the qBittorrent WebUI URL in a browser to confirm authentication requirements.
Validate settings completeness before calling IsApiSupported.

When it happens

Trigger: IsApiSupported is called (during download client initialization) against a qBittorrent instance that returns 401 on the unauthenticated webapiVersion request.

Common situations: Fresh qBittorrent install with default security settings requiring auth; credentials not configured in the download client; qBittorrent accessed remotely with localhost auth bypass disabled; qBittorrent auth settings changed.

Related errors

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