What causes "Mount point %s cannot be an existing folder" in juicedata/juicefs?

Remove or rename the existing directory before mounting: rmdir /s /q (ensure it is empty).

Mount point %s cannot be an existing folder

Error message

Mount point %s cannot be an existing folder

What it means

For a non-drive mountpoint, the WinFsp layer requires the mount point path to NOT already exist — WinFsp creates it as a volume mount point itself. If os.Stat(conf.Mountpoint) succeeds (path exists), mounting is refused with this error.

Source

Thrown at pkg/winfsp/winfs.go:1177

		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
	}

	return fmt.Errorf("juicefs mount command exit with error, please check the log for details")
}

View on GitHub (pinned to c9a67b23e8)

Solutions

Remove or rename the existing directory before mounting: rmdir /s /q <path> (ensure it is empty).
Re-run the mount command; WinFsp will create the mount point.
If a stale folder remains from a crashed mount, clean it up after stopping the WinFsp service.
Adjust provisioning scripts to not pre-create the mountpoint for WinFsp mounts.

Example fix

// shell
# before
mkdir C:\jfs && juicefs mount sqlite3://test.db C:\jfs --as-local-volume
# after
juicefs mount sqlite3://test.db C:\jfs --as-local-volume

Defensive patterns

Strategy: validation

Validate before calling

// PowerShell: ensure mountpoint does not pre-exist
$mp = 'C:\jfs'
if (Test-Path $mp) { Remove-Item $mp -Force -Recurse -ErrorAction SilentlyContinue }

Try / catch

if err := runMount(); err != nil && strings.Contains(err.Error(), "cannot be an existing folder") {
    os.RemoveAll(mp) // after confirming it is safe/empty
    err = runMount()
}

Prevention

Never pre-create the WinFsp mount directory.
Provision parent directories only, not the leaf mountpoint.
Clean stale folders after unclean shutdowns.
Update Ansible/Terraform roles to skip mkdir for WinFsp targets.

When it happens

Trigger: Mounting with --as-local-volume (or a non-drive path) where os.Stat(mountpoint) returns no error because the directory already exists on disk (e.g. pre-created with mkdir).

Common situations: Users pre-create the mount directory out of Linux habit before mounting; re-running a mount after an unclean previous teardown left the folder behind; provisioning tools (Ansible/Terraform) create the directory first.

Understand the failure class

Background: "already exists" / EEXIST / FileAlreadyExistsException: what the 'file already exists' error means and how to fix it — this error's family across 37 libraries.

Related errors

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