AlistGo/alist · error

failed to add offline download task: %w

Error message

failed to add offline download task: %w

What it means

GuangYaPan.AddURL() calls driver.OfflineDownload() after making the parent directory, and wraps any failure with 'failed to add offline download task'. The real cause is in the wrapped error: authentication loss, unsupported/invalid URL, quota exhaustion, or an API error from the GuangYaPan service.

Source

Thrown at internal/offline_download/guangyapan/guangyapan.go:74

	if err != nil {
		return "", err
	}
	driver, ok := storage.(*guangyapandriver.GuangYaPan)
	if !ok {
		return "", errors.New("GuangYaPan offline download only supports GuangYaPan destination storage")
	}

	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 := driver.OfflineDownload(ctx, args.Url, parentDir, "")
	if err != nil {
		return "", fmt.Errorf("failed to add offline download task: %w", err)
	}
	return task.TaskID, nil
}

func (g *GuangYaPan) Remove(task *tool.DownloadTask) error {
	storage, _, err := op.GetStorageAndActualPath(task.TempDir)
	if err != nil {
		return err
	}
	driver, ok := storage.(*guangyapandriver.GuangYaPan)
	if !ok {
		return errors.New("GuangYaPan offline download only supports GuangYaPan destination storage")
	}
	ctx := context.Background()
	if err := driver.DeleteOfflineTasks(ctx, []string{task.GID}, false); err != nil {
		return err
	}
	g.DelTaskCache(driver, task.GID)

View on GitHub (pinned to 843d9dc814)

Solutions

1. Read the wrapped (%w) error text to identify the underlying cause first
2. Refresh the storage's authentication (re-login / update token) in the storage settings and retry
3. Verify the URL is a supported direct download link by testing it on the GuangYaPan site
4. Retry after a delay if the wrapped error indicates rate limiting or quota

Example fix

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

// caller: unwrap to distinguish auth vs URL problems
var apiErr *panErr.APIError
if errors.As(err, &apiErr) && apiErr.Code == codeUnauthorized {
    // refresh credentials then retry once
}

gid, err := g.AddURL(args)
if err != nil {
    if strings.Contains(err.Error(), "failed to add offline download task") {
        cause := errors.Unwrap(err)
        if isAuthError(cause) {
            refreshGuangYaPanAuth(storage) // then let the user retry once
        }
        return fmt.Errorf("guangyapan rejected the task: %v", cause)
    }
    return err
}

When it happens

Trigger: Posting an offline download URL via the API with tool=guangyapan when the driver's stored token/cookie has expired, the URL is not a direct download link the service accepts, or the account hit its offline-download task quota.

Common situations: GuangYaPan login credentials expired since the storage was added; user pastes a magnet or streaming page URL the platform rejects; rate limiting after adding many tasks in a burst.

Related errors

• failed to add offline download task: %w
• failed to add offline download task: %w
• offline url is empty
• create offline task failed: empty task id
• GuangYaPan offline download only supports GuangYaPan destina

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