What causes "failed to add offline download task: %w" in AlistGo/alist?

Inspect the wrapped error message for the platform's own failure reason

failed to add offline download task: %w

Error message

failed to add offline download task: %w

What it means

PikPak.AddURL() wraps any failure of pikpakDriver.OfflineDownload() with 'failed to add offline download task'. The underlying cause rides in the %w chain: expired PikPak token, magnet/URL rejected by the platform, vip-only resource restrictions, or API errors.

Source

Thrown at internal/offline_download/pikpak/pikpak.go:78

	pikpakDriver, ok := storage.(*pikpak.PikPak)
	if !ok {
		return "", fmt.Errorf("unsupported storage driver for offline download, only Pikpak 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
	}

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

	return t.ID, nil
}

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

View on GitHub (pinned to 843d9dc814)

Solutions

Inspect the wrapped error message for the platform's own failure reason
Refresh PikPak credentials on the storage and retry the add
Test the same link in the PikPak app to confirm it is accepted for your account tier
Retry with backoff if the wrapped error is a rate/limit message

Example fix

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

// caller-side: single retry after re-auth on auth errors
if strings.Contains(err.Error(), "token") {
    refreshPikPakToken(storage)
    t, err = pikpakDriver.OfflineDownload(ctx, args.Url, parentDir, "")
}

Defensive patterns

Strategy: try-catch

Try / catch

id, err := p.AddURL(args)
if err != nil {
    if strings.Contains(err.Error(), "failed to add offline download task") {
        cause := errors.Unwrap(err)
        if isTokenError(cause) {
            return retryAfterReauth(args) // single controlled retry
        }
        return fmt.Errorf("pikpak refused task: %v", cause)
    }
    return err
}

Prevention

Refresh PikPak tokens proactively on a schedule shorter than their lifetime
Distinguish auth vs quota vs link errors from the wrapped cause before retrying
Never blind-retry in a tight loop; rate limits make it worse

When it happens

Trigger: Submitting a URL or magnet with tool=pikpak after the stored PikPak credentials expired, when the platform refuses the link (copyright/vip restriction), or when the parent directory lookup produced an invalid target.

Common situations: Long-running deployments whose PikPak login token lapsed; sharing links that require a paid PikPak plan; adding many tasks rapidly and hitting API rate limits.

Related errors

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