AlistGo/alist · error

resolve root folder path failed: folder %q not found under /

Error message

resolve root folder path failed: folder %q not found under /

What it means

Thrown while resolving the configured RootPath: the driver paginated through the children of the root directory (/) and no folder named `name` was found, so parentID stayed empty. It is a path-configuration error surfaced by resolveRootFolderID, not an API failure.

Source

Thrown at drivers/guangyapan/driver.go:522

		if err := d.postAPI(ctx, "/nd.bizuserres.s/v1/file/get_file_list", body, &resp); err != nil {
			return "", err
		}
		for _, item := range resp.Data.List {
			seen++
			if item.ResType == 2 && item.FileName == name {
				return item.FileID, nil
			}
		}
		if len(resp.Data.List) < pageSize {
			break
		}
		if resp.Data.Total > 0 && seen >= resp.Data.Total {
			break
		}
	}

	if parentID == "" {
		return "", fmt.Errorf("resolve root folder path failed: folder %q not found under /", name)
	}
	return "", fmt.Errorf("resolve root folder path failed: folder %q not found under parent %s", name, parentID)
}

func (d *GuangYaPan) ensureAccessToken(ctx context.Context) error {
	if strings.TrimSpace(d.AccessToken) != "" {
		return nil
	}
	if strings.TrimSpace(d.RefreshToken) == "" {
		if d.canSMSLogin() {
			return d.loginBySMSCode(ctx)
		}
		if d.PhoneNumber != "" {
			return errors.New("not logged in yet: please fill verify_code and save storage to finish SMS login")
		}
		return errors.New("access token is empty")
	}
	return d.refreshToken(ctx)

View on GitHub (pinned to 843d9dc814)

Solutions

1. Verify the exact folder name exists directly under / on GuangYaPan (web UI) and fix RootPath to match.
2. Remove stray slashes/spaces from RootPath; use a path like /backup not backup/ or //backup.
3. Re-check that the logged-in account can see that folder.
4. If the folder genuinely must exist, create it under / first or point RootPath at /.

// before saving storage config, confirm the path is clean
p := strings.TrimSpace(cfg.RootPath)
p = strings.Trim(p, "/")
if p == "" || strings.Contains(p, "//") {
    return errors.New("root_folder_path must be a clean path like /backup")
}

if err := storage.Init(ctx); err != nil {
    if strings.Contains(err.Error(), "resolve root folder path failed") {
        // config error: show the user which folder name failed, do not retry
        return fmt.Errorf("check root_folder_path: %w", err)
    }
}

When it happens

Trigger: Init/directory listing calls resolveRootFolderID for the first path segment of RootPath and, after scanning all pages (loop exits when page is short or seen >= total), no entry matches that name under /.

Common situations: RootPath in the storage config references a folder that was renamed or deleted on GuangYaPan; typo or leading/trailing slash in RootPath; the folder exists but is invisible because the account lacks permission or the API pagination total is inaccurate.

Related errors

• resolve root folder path failed: folder %q not found under p
• login failed: provide a valid access_token, or refresh_token
• upload token is incomplete
• not logged in yet: please fill verify_code and save storage
• {message}

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