AlistGo/alist · error

failed to add qBittorrent task

Error message

failed to add qBittorrent task: {link}

What it means

Adding a torrent/magnet to qBittorrent via /api/v2/torrents/add failed: the HTTP status was not 200 or the response body was not "Ok". The error embeds the submitted link so you can see which one failed.

Solutions

  1. Validate the magnet URI format (must contain xt=urn:btih:...) or the .torrent URL before submitting
  2. Check the qBittorrent download directory exists and is writable
  3. Re-verify login/authorization (the 403 case) and retry after re-login

Example fix

// before
err := c.AddTorrentTask("magnet:?xt=btih:WRONGHASH", "", false)

// after
magnet := "magnet:?xt=urn:btih:<40-char-infohash>&dn=name"
err := c.AddTorrentTask(magnet, "", false)
Defensive patterns

Strategy: validation

Validate before calling

func validMagnet(m string) bool {
	return strings.HasPrefix(m, "magnet:?") && strings.Contains(m, "xt=urn:btih:")
}
if !validMagnet(link) && !strings.HasSuffix(link, ".torrent") {
	return errors.New("not a valid magnet or torrent link")
}

Try / catch

err := c.AddTorrentTask(link, "", false)
if err != nil && strings.Contains(err.Error(), "failed to add qBittorrent task") {
	log.Warnf("qBittorrent rejected link %q (status/body mismatch)", link)
}

Prevention

When it happens

Trigger: Calling AddTorrentTask with a malformed magnet URI or .torrent link, an unreachable URL for URL-based downloads, a session that lost authorization, or a full/inaccessible download directory.

Common situations: Magnet link truncated or with a bad xt hash; torrent file URL requiring auth; qBittorrent's default save path missing (removed disk); WebUI session cookie expired mid-operation.

Related errors


AI-assisted analysis of AlistGo/alist@843d9dc814 (2026-08-15). Data as JSON: /api/errors/03739483753b5dc9. Report an issue: GitHub.

Appendix: source

Thrown at pkg/qbittorrent/client.go:168

	req, err := http.NewRequest("POST", u.String(), buf)
	if err != nil {
		return err
	}
	req.Header.Add("Content-Type", writer.FormDataContentType())

	resp, err := c.client.Do(req)
	if err != nil {
		return err
	}

	// check result
	body := make([]byte, 2)
	_, err = resp.Body.Read(body)
	if err != nil {
		return err
	}
	if resp.StatusCode != 200 || string(body) != "Ok" {
		return errors.New("failed to add qBittorrent task: " + link)
	}
	return nil
}

type TorrentStatus string

const (
	ERROR              TorrentStatus = "error"
	MISSINGFILES       TorrentStatus = "missingFiles"
	UPLOADING          TorrentStatus = "uploading"
	PAUSEDUP           TorrentStatus = "pausedUP"
	QUEUEDUP           TorrentStatus = "queuedUP"
	STALLEDUP          TorrentStatus = "stalledUP"
	CHECKINGUP         TorrentStatus = "checkingUP"
	FORCEDUP           TorrentStatus = "forcedUP"
	ALLOCATING         TorrentStatus = "allocating"
	DOWNLOADING        TorrentStatus = "downloading"
	METADL             TorrentStatus = "metaDL"

View on GitHub (pinned to 843d9dc814)