AlistGo/alist · error

rename failed: %s

Error message

rename failed: %s

What it means

GuangYaPan Rename error: /file/rename returned HTTP success but msg != 'success', surfaced as 'rename failed: <backend msg>'. The backend message explains the rejection, e.g. name conflicts or forbidden characters.

Source

Thrown at drivers/guangyapan/driver.go:288

	fileID := strings.TrimSpace(srcObj.GetID())
	if fileID == "" {
		return errors.New("file id is empty")
	}
	name := strings.TrimSpace(newName)
	if name == "" {
		return errors.New("new name is empty")
	}

	var out commonResp
	if err := d.postAPI(ctx, "/nd.bizuserres.s/v1/file/rename", map[string]any{
		"fileId":  fileID,
		"newName": name,
	}, &out); err != nil {
		return err
	}
	if !strings.EqualFold(strings.TrimSpace(out.Msg), "success") {
		return fmt.Errorf("rename failed: %s", strings.TrimSpace(out.Msg))
	}
	return nil
}

func (d *GuangYaPan) Remove(ctx context.Context, obj model.Obj) error {
	if err := d.ensureAccessToken(ctx); err != nil {
		return err
	}

	fileID := strings.TrimSpace(obj.GetID())
	if fileID == "" {
		return errors.New("file id is empty")
	}

	var del deleteResp
	if err := d.postAPI(ctx, "/nd.bizuserres.s/v1/file/delete_file", map[string]any{
		"fileIds": []string{fileID},
	}, &del); err != nil {

View on GitHub (pinned to 843d9dc814)

Solutions

  1. Inspect the backend msg appended to the error for the precise cause
  2. Ensure the target name is unique within the folder and uses allowed characters
  3. Retry after any in-flight server-side task (move/copy) on the same file completes
  4. Refresh the object listing so fileID matches the current upstream state
Defensive patterns

Strategy: try-catch

Validate before calling

func safeNewName(parentListing []model.Obj, newName string) bool {
  for _, o := range parentListing { if o.GetName() == newName { return false } }
  return strings.TrimSpace(newName) != ""
}

Try / catch

err := d.Rename(ctx, srcObj, newName)
if err != nil && strings.HasPrefix(err.Error(), "rename failed") {
  // surface backend msg to user; retry only after confirming no name conflict
}

Prevention

When it happens

Trigger: Calling Rename with a newName that already exists in the same folder, an empty-after-trim name (guarded earlier), or a fileID the backend considers invalid/locked, causing the rename endpoint to report a non-success msg.

Common situations: Renaming to an existing name in the same directory; backend character validation on names; renaming a file involved in a pending server-side task; stale file ID after upstream re-organization.

Related errors

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