restore command requires Administrator or elevated privilege

Error message

restore command requires Administrator or elevated privilege on Windows

What it means

The 'restore' command reads and rewrites trash metadata and file attributes, which on Windows requires elevated rights. Before doing anything else, restore checks whether the process runs as Administrator (or an elevated process) via utils.IsWinAdminOrElevatedPrivilege and aborts with this error when it does not. Non-Windows systems are checked separately against root (uid 0).

Source

Thrown at cmd/restore.go:47

$ juicefs restore redis://localhost/1 2023-05-10-01`,
		Flags: []cli.Flag{
			&cli.BoolFlag{
				Name:  "put-back",
				Usage: "move the recovered files into original directory",
			},
			&cli.IntFlag{
				Name:  "threads",
				Value: 10,
				Usage: "number of threads",
			},
		},
	}
}

func restore(ctx *cli.Context) error {
	setup0(ctx, 2, 0)
	if runtime.GOOS == "windows" && !utils.IsWinAdminOrElevatedPrivilege() {
		return fmt.Errorf("restore command requires Administrator or elevated privilege on Windows")
	}
	if os.Getuid() != 0 && runtime.GOOS != "windows" {
		return fmt.Errorf("only root can restore files from trash")
	}
	removePassword(ctx.Args().Get(0))
	m := meta.NewClient(ctx.Args().Get(0), nil)
	_, err := m.Load(true)
	if err != nil {
		return err
	}
	for i := 1; i < ctx.NArg(); i++ {
		hour := ctx.Args().Get(i)
		doRestore(m, hour, ctx.Bool("put-back"), ctx.Int("threads"))
	}
	return nil
}

func doRestore(m meta.Meta, hour string, putBack bool, threads int) {

View on GitHub (pinned to c9a67b23e8)

Solutions

Relaunch the shell or command with 'Run as administrator' and rerun the restore.
From an elevated PowerShell: Start-Process juicefs -ArgumentList 'restore ...' -Verb RunAs.
For scheduled tasks, enable 'Run with highest privileges' for the task.
Alternatively run the restore from a root account on a Linux client pointed at the same metadata engine.

Example fix

// before (non-elevated PowerShell)
juicefs restore redis://:pass@host:6379/1 /trash-file
// after (elevated PowerShell)
Start-Process -Verb RunAs -Wait juicefs -ArgumentList 'restore','redis://:pass@host:6379/1','/trash-file'

Defensive patterns

Strategy: validation

Validate before calling

# PowerShell pre-check before running restore
$isAdmin = ([Security.Principal.WindowsPrincipal][Security.Principal.WindowsIdentity]::GetCurrent()).IsInRole([Security.Principal.WindowsBuiltInRole]::Administrator)
if (-not $isAdmin) { throw "Run this script from an elevated (Administrator) shell." }

Try / catch

err := exec.Command("juicefs", "restore", metaURL, target).Run()
if err != nil && strings.Contains(err.Error(), "requires Administrator") {
    // relaunch elevated via powershell Start-Process -Verb RunAs
}

Prevention

Open an elevated terminal (Run as administrator) before any trash restore work on Windows.
Set scheduled tasks/CI jobs to 'Run with highest privileges' when they call restore.
Check elevation programmatically with IsWinAdminOrElevatedPrivilege-style logic before launching.
Prefer Linux root clients for scripted restores when elevation on Windows is impractical.

When it happens

Trigger: Running `juicefs restore <meta-url> ...` on Windows from a normal (non-elevated) shell, e.g. a regular cmd/PowerShell window or a non-elevated scheduled task; runtime.GOOS == "windows" and IsWinAdminOrElevatedPrivilege() returns false.

Common situations: Double-clicking or scripting juicefs.exe without 'Run as administrator'; CI agents on Windows runners lacking elevation; an elevated terminal requirement forgotten after switching to a standard user account.

Understand the failure class

Background: Permission denied / not authorized / 403 Forbidden: access-control rejections when the caller lacks the required role, grant, or ownership — this error's family across 18 libraries.

Related errors

AI-assisted analysis of juicedata/juicefs@c9a67b23e8 (2026-09-06). Data as JSON: /api/errors/8d50eb2de617761d. Report an issue: GitHub.