What causes "missing file path" in AlistGo/alist?

Populate the object's Path from the listing before calling download (e.g. join parent path + name)

missing file path

Error message

missing file path

What it means

A guard in cookieDownloadURLOnce: the cookie-mode download form requires fname (the normalized remote path). If normalizeRemotePath(file.GetPath()) yields an empty string, the request is rejected before it is sent (drivers/yunpan360/util.go:349).

Source

Thrown at drivers/yunpan360/util.go:349

func (d *Yunpan360) cookieDownloadURL(ctx context.Context, file model.Obj) (*CookieDownloadResp, error) {
	resp, err := d.cookieDownloadURLOnce(ctx, file, false)
	if err == nil {
		return resp, nil
	}

	d.invalidateCookieDownloadSession()
	return d.cookieDownloadURLOnce(ctx, file, true)
}

func (d *Yunpan360) cookieDownloadURLOnce(ctx context.Context, file model.Obj, refresh bool) (*CookieDownloadResp, error) {
	nid := strings.TrimSpace(file.GetID())
	if nid == "" {
		return nil, errors.New("missing file id")
	}

	fname := normalizeRemotePath(file.GetPath())
	if fname == "" {
		return nil, errors.New("missing file path")
	}

	ownerQID, token, err := d.resolveCookieDownloadParams(ctx, file, refresh)
	if err != nil {
		return nil, err
	}

	var resp CookieDownloadResp
	err = d.cookieRequestForm(ctx, downloadPath, map[string]string{
		"nid":       nid,
		"fname":     fname,
		"owner_qid": ownerQID,
		"token":     token,
	}, &resp)
	if err != nil {
		return nil, err
	}
	return &resp, nil

View on GitHub (pinned to 843d9dc814)

Solutions

Populate the object's Path from the listing before calling download (e.g. join parent path + name)
Verify the obj passed to Link comes from the driver's List output
If only the ID is known, first List the parent to obtain the full path

Example fix

// before
obj := &model.Object{ID: "123456789"} // path empty

// after
obj := &model.Object{ID: "123456789", Path: "/docs/a.txt", Name: "a.txt"}

Defensive patterns

Strategy: validation

Validate before calling

if normalizeRemotePath(file.GetPath()) == "" { return errors.New("refusing download: object has no path") }

Type guard

func hasFilePath(obj model.Obj) bool { return normalizeRemotePath(obj.GetPath()) != "" }

Try / catch

if !hasFilePath(file) { return nil, errors.New("object lacks path; re-list to populate") }
return d.cookieDownloadURL(ctx, file)

Prevention

When building objects, always compute Path as parent + '/' + name
Round-trip objects through typed structs, not ad-hoc maps, to keep Path
Validate both ID and Path before calling Link()

When it happens

Trigger: Calling download with a model.Obj whose Path is empty, "/", or only whitespace/slashes so that normalizeRemotePath returns "". Typical with hand-constructed objects or objects whose path was dropped during serialization.

Common situations: Caller builds model.Obj from just an ID and forgets Path; object passed through JSON round-trip where path field was tagged differently (path vs name confusion); root-level objects with empty paths used for download.

Related errors

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