AlistGo/alist · error

failed to add offline download task: %w

Error message

failed to add offline download task: %w

What it means

Thunder.AddURL() wraps failures of thunderDriver.OfflineDownload() with 'failed to add offline download task'. The wrapped error carries the actual cause: expired Thunder login (captcha/QR re-auth needed), link refused by the platform, or quota limits on the Xunlei account.

Source

Thrown at internal/offline_download/thunder/thunder.go:79

	thunderDriver, ok := storage.(*thunder.Thunder)
	if !ok {
		return "", fmt.Errorf("unsupported storage driver for offline download, only Thunder is supported")
	}

	ctx := context.Background()

	if err := op.MakeDir(ctx, storage, actualPath); err != nil {
		return "", err
	}

	parentDir, err := op.GetUnwrap(ctx, storage, actualPath)
	if err != nil {
		return "", err
	}

	task, err := thunderDriver.OfflineDownload(ctx, args.Url, parentDir, "")
	if err != nil {
		return "", fmt.Errorf("failed to add offline download task: %w", err)
	}

	return task.ID, nil
}

func (t *Thunder) Remove(task *tool.DownloadTask) error {
	storage, _, err := op.GetStorageAndActualPath(task.TempDir)
	if err != nil {
		return err
	}
	thunderDriver, ok := storage.(*thunder.Thunder)
	if !ok {
		return fmt.Errorf("unsupported storage driver for offline download, only Thunder is supported")
	}
	ctx := context.Background()
	err = thunderDriver.DeleteOfflineTasks(ctx, []string{task.GID}, false)
	if err != nil {
		return err

View on GitHub (pinned to 843d9dc814)

Solutions

1. Unwrap and read the underlying error for the platform's reason
2. Re-authenticate the Thunder storage (fresh QR login in storage settings) and retry
3. Verify the link downloads in the official Thunder client for the same account
4. Wait and retry if the wrapped error reports quota/rate limits

Example fix

task, err := thunderDriver.OfflineDownload(ctx, args.Url, parentDir, "")
if err != nil {
    return "", fmt.Errorf("failed to add offline download task: %w", err)
}

// caller: surface the wrapped cause to the user
if err != nil {
    log.Warnf("thunder add failed: %v", errors.Unwrap(err))
}

id, err := t.AddURL(args)
if err != nil {
    if strings.Contains(err.Error(), "failed to add offline download task") {
        cause := errors.Unwrap(err)
        if isSessionExpired(cause) {
            return errorWithHint(cause, "re-scan QR login for the Thunder storage, then retry")
        }
        return fmt.Errorf("thunder refused task: %v", cause)
    }
    return err
}

When it happens

Trigger: Submitting a URL/magnet with tool=thunder when the stored Thunder session expired, when the resource is unavailable to the account, or when the daily offline-task quota is exhausted.

Common situations: Thunder sessions expiring every few weeks and requiring re-scan of the QR login; links behind vip restrictions; adding magnet links the platform does not resolve.

Related errors

• failed to add offline download task: %w
• failed to add offline download task: %w
• share_ids is required
• refresh token is empty
• SafePassword is incorrect

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