AlistGo/alist · error

unsupported storage driver for offline download, only…

Error message

unsupported storage driver for offline download, only Pikpak is supported

What it means

PikPak.AddURL() resolves storage from args.TempDir and type-asserts it to *pikpak.PikPak before submitting the offline task. Any other driver behind the mount fails the assertion. PikPak offline downloads must target a PikPak storage mount because the file lands directly in that cloud drive.

Solutions

  1. Point the temp/save directory at the PikPak storage mount
  2. Or pick the tool that matches the destination storage (http/aria2 for local)
  3. Confirm the storage's driver reads 'PikPak' in the admin storages list

Example fix

// before
{ "tool": "pikpak", "temp_dir": "/local/tmp" }

// after
{ "tool": "pikpak", "temp_dir": "/pikpak/tmp" }
Defensive patterns

Strategy: type-guard

Validate before calling

storage, _, err := op.GetStorageAndActualPath(args.TempDir)
if err != nil {
    return err
}
if storage.Driver != "PikPak" {
    return fmt.Errorf("pikpak tool requires a PikPak mount, got %s", storage.Driver)
}

Type guard

func asPikPak(tempDir string) (*pikpak.PikPak, error) {
    storage, _, err := op.GetStorageAndActualPath(tempDir)
    if err != nil {
        return nil, err
    }
    d, ok := storage.(*pikpak.PikPak)
    if !ok {
        return nil, fmt.Errorf("%s is on %q storage, need PikPak", tempDir, storage.Driver)
    }
    return d, nil
}

Try / catch

if _, err := p.AddURL(args); err != nil {
    if strings.Contains(err.Error(), "only Pikpak is supported") {
        return userError("select a PikPak storage directory for this tool")
    }
    return err
}

Prevention

When it happens

Trigger: Adding an offline URL with tool=pikpak while args.TempDir is on local storage or a non-PikPak cloud mount; the PikPak storage was unmounted between task creation and add.

Common situations: Tool/directory mismatch in the offline download settings UI; users assuming PikPak downloads to server disk; mount path prefix shadowed by another storage.

Related errors


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

Appendix: source

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

	if err != nil {
		return false
	}
	if _, ok := storage.(*pikpak.PikPak); !ok {
		return false
	}
	return true
}

func (p *PikPak) AddURL(args *tool.AddUrlArgs) (string, error) {
	// 添加新任务刷新缓存
	p.refreshTaskCache = true
	storage, actualPath, err := op.GetStorageAndActualPath(args.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()

	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)
	}

View on GitHub (pinned to 843d9dc814)