AlistGo/alist · warning

invalid file_name

Error message

invalid file_name

What it means

Returned by GetLabelByFileName when url.QueryUnescape fails on the file_name query value, meaning the value contains a malformed percent-escape sequence (e.g. a lone '%' or invalid hex like '%zz'). gin already URL-decodes query parameters once, so this second decode expects the caller to have double-encoded the filename.

Source

Thrown at server/handles/label_file_binding.go:40

	Content []T   `json:"content"`
	Total   int64 `json:"total"`
}

type restoreLabelBindingsReq struct {
	KeepIDs  bool                     `json:"keep_ids"`
	Override bool                     `json:"override"`
	Bindings []model.LabelFileBinding `json:"bindings"`
}

func GetLabelByFileName(c *gin.Context) {
	fileName := c.Query("file_name")
	if fileName == "" {
		common.ErrorResp(c, errors.New("file_name must not empty"), 400)
		return
	}
	decodedFileName, err := url.QueryUnescape(fileName)
	if err != nil {
		common.ErrorResp(c, errors.New("invalid file_name"), 400)
		return
	}
	fmt.Println(">>> 原始 fileName:", fileName)
	fmt.Println(">>> 解码后 fileName:", decodedFileName)
	userObj, ok := c.Value("user").(*model.User)
	if !ok {
		common.ErrorStrResp(c, "user invalid", 401)
		return
	}
	labels, err := op.GetLabelByFileName(userObj.ID, decodedFileName)
	if err != nil {
		common.ErrorResp(c, err, 500, true)
		return
	}
	common.SuccessResp(c, labels)
}

func CreateLabelFileBinDing(c *gin.Context) {

View on GitHub (pinned to 843d9dc814)

Solutions

1. URL-encode the filename client-side so every '%' becomes '%25' before it reaches the query string
2. If the filename has no special characters, pass it plain (but still encode '%' and '&')
3. For filenames with '%' or '+', verify the exact bytes received server-side to debug double-encoding

Example fix

// before
GET /api/label/file?file_name=/reports/100%off.pdf
// after
GET /api/label/file?file_name=%2Freports%2F100%25off.pdf

// Pre-validate the escape sequence the server will QueryUnescape
var badEscape = regexp.MustCompile(`%(?![0-9A-Fa-f]{2})`)
if badEscape.MatchString(fileName) {
    fileName = url.QueryEscape(fileName)
}

if resp.StatusCode() == 400 && strings.Contains(resp.String(), "invalid file_name") {
    // re-send with full percent-encoding of the filename
}

When it happens

Trigger: Passing file_name with a raw '%' not part of a valid escape, or passing a once-encoded value that gin already decoded leaving stray escapes; e.g. ?file_name=100%progress.

Common situations: Filenames containing literal percent signs (progress trackers, '50%off.pdf'); clients that pre-encode the value while gin encodes/decodes it again, producing half-decoded input; mixing encoded slashes incorrectly.

Related errors

• label name is exists
• file_name must not empty
• share_id must be 1-32 characters of letters, numbers, unders
• invalid request
• invalid label ID '%s': %v

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