juicedata/juicefs · error

Cannot mount to a local directory when --as-local-volume is

Error message

Cannot mount to a local directory when --as-local-volume is not set

What it means

WinFsp mount configuration rejects a mountpoint that is a local directory path when the volume is not being mounted as a network drive (--as-local-volume not set). WinFsp in network-drive mode can only expose the volume on a drive letter, so pointing it at a directory path is invalid without the local-volume option.

Source

Thrown at pkg/winfsp/winfs.go:1172

	if winfspDbgLog != "" {
		logger.Infof("WinFsp Debug Log Path: %s", winfspDbgLog)
		options += ",debug,DebugLog=" + winfspDbgLog
	}
	if flushOnCleanup {
		options += ",FlushOnCleanup=1"
	}

	host.SetCapCaseInsensitive(!caseSensitive)
	host.SetCapReaddirPlus(true)

	mountVolumeName := filepath.VolumeName(conf.Mountpoint)
	mountPointIsDrive := isDriveByVolumeName(conf.Mountpoint)
	if mountPointIsDrive {
		conf.Mountpoint = mountVolumeName
	}

	if !mountPointIsDrive && mountAsNetworkDrive {
		return fmt.Errorf("Cannot mount to a local directory when --as-local-volume is not set")
	}

	if !mountPointIsDrive {
		if _, err := os.Stat(conf.Mountpoint); err == nil {
			return fmt.Errorf("Mount point %s cannot be an existing folder", conf.Mountpoint)
		}

		// the parent directory of the mount point must exist
		parentDir := filepath.Dir(conf.Mountpoint)
		if _, err := os.Stat(parentDir); os.IsNotExist(err) {
			return fmt.Errorf("Parent directory %s of mount point %s does not exist", parentDir, conf.Mountpoint)
		}
	}

	logger.Debugf("mount point: %s, mountPointIsDrive: %v, options: %s", conf.Mountpoint, mountPointIsDrive, options)
	exitOk := host.Mount(conf.Mountpoint, []string{"-o", options})
	if exitOk {
		return nil

View on GitHub (pinned to c9a67b23e8)

Solutions

1. Use a free drive letter as the mountpoint (e.g. Z:) instead of a directory path.
2. Add --as-local-volume to mount onto a local directory path.
3. Update automation/scripts targeting Windows to use drive letters or the flag.
4. Check the resolved mountpoint: ensure isDriveByVolumeName logic matches the format you pass (e.g. 'Z:' vs 'Z:\').

Example fix

// before
juicefs mount sqlite3://test.db C:\jfs
// after
juicefs mount sqlite3://test.db C:\jfs --as-local-volume
# or
juicefs mount sqlite3://test.db Z:

// PowerShell: validate mountpoint before invoking juicefs
$mp = 'C:\jfs'
$isDrive = $mp -match '^[A-Za-z]:$'
if (-not $isDrive -and -not ($args -contains '--as-local-volume')) {
    throw "Use a drive letter or pass --as-local-volume for $mp"
}

out, err := exec.Command("juicefs", "mount", meta, mp).CombinedOutput()
if err != nil && strings.Contains(string(out), "--as-local-volume") {
    out, err = exec.Command("juicefs", "mount", meta, mp, "--as-local-volume").CombinedOutput()
}

When it happens

Trigger: Calling the WinFsp Mount entry (pkg/winfsp/winfs.go:1172 region) with conf.Mountpoint that is not a drive letter (isDriveByVolumeName returns false) while mountAsNetworkDrive is true and the user did not pass --as-local-volume.

Common situations: Users running `juicefs mount meta:// /mnt/jfs` on Windows expecting Linux-style directory mounts; scripts copied from Unix hosts; forgetting --as-local-volume when mounting into a folder.

Understand the failure class

Background: "Invalid value" and "allowed values are" config errors: what your library rejected and how to fix it — this error's family across 41 libraries.

Related errors

• Mount point %s cannot be an existing folder
• Parent directory %s of mount point %s does not exist
• juicefs mount command exit with error, please check the log
• Mount command succeeded, but the mountpoint %s did not becom
• failed to get mount command: %v

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