What causes "file_name must not empty" in AlistGo/alist?

Pass a non-empty file_name query parameter, URL-encoded: ?file_name=%2Fpath%2Fto%2Ffile

file_name must not empty

Error message

file_name must not empty

What it means

Returned by GetLabelByFileName (server/handles/label_file_binding.go:36-39) when the required 'file_name' query parameter is missing or empty. The handler reads c.Query("file_name"), rejects empty values with HTTP 400, then URL-decodes the value for the lookup. Note the handler also contains leftover debug fmt.Println statements (Chinese-prefixed) that leak the raw and decoded filename to stdout on every call.

Source

Thrown at server/handles/label_file_binding.go:35

	FileName string `json:"file_name"`
	LabelId  string `json:"label_id"`
}

type pageResp[T any] struct {
	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

View on GitHub (pinned to 843d9dc814)

Solutions

Pass a non-empty file_name query parameter, URL-encoded: ?file_name=%2Fpath%2Fto%2Ffile
Check client-side that the path variable is defined before issuing the request
Operators: remove the debug fmt.Println lines (they log every queried filename)

Example fix

// before
GET /api/label/file
// after
GET /api/label/file?file_name=%2Fdocs%2Freport.pdf

Defensive patterns

Strategy: validation

Validate before calling

if fileName == "" {
    return errors.New("file_name query parameter is required")
}
url := base + "/api/label/file?file_name=" + url.QueryEscape(fileName)

Try / catch

if resp.StatusCode() == 400 && strings.Contains(resp.String(), "file_name must not empty") {
    // caller bug: request URL was built without the query param — fix at the call site
}

Prevention

Assert required query params in a shared request-builder instead of ad-hoc string concat
Beware: gin decodes once, this handler decodes again — escape '%' as '%25'
Remove the handler's leftover debug fmt.Println lines in production builds

When it happens

Trigger: Calling the label-by-file endpoint without ?file_name=... or with ?file_name= (empty value).

Common situations: Frontend builds the URL from a variable that is undefined for virtual/root paths; curl invocations forgetting the query string; URL-encoding bugs that collapse the parameter to empty.

Related errors

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