juicefs mount command exit with error, please check the log

Error message

juicefs mount command exit with error, please check the log for details

What it means

After validating the mountpoint, the code calls host.Mount, which returns a boolean success flag rather than an error. If it returns false, the WinFsp host failed to mount (or the service exited with failure), and this generic message is returned directing the user to the logs, since the detailed reason is only recorded there.

Source

Thrown at pkg/winfsp/winfs.go:1193

	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")
}

const winfspSecurityDescriptor = "D:P(A;;RPWPLC;;;WD)"

func updateWinFspRegService(winfspServiceName string, cmdLine string, alias string, logPath string, asNetworkDrive bool) error {
	regKeyPath := "SOFTWARE\\WOW6432Node\\WinFsp\\Services\\" + winfspServiceName
	k, err := registry.OpenKey(registry.LOCAL_MACHINE, regKeyPath, registry.ALL_ACCESS)
	if err != nil {
		if err == syscall.ERROR_FILE_NOT_FOUND || err == syscall.ERROR_PATH_NOT_FOUND {
			logger.Info("WinFsp service registry key not found, creating it.")
			k, _, err = registry.CreateKey(registry.LOCAL_MACHINE, regKeyPath, registry.ALL_ACCESS)
			if err != nil {
				return fmt.Errorf("Failed to create registry key: %s", err)
			}
		} else {
			return fmt.Errorf("Failed to open registry key: %s", err)
		}
	}

View on GitHub (pinned to c9a67b23e8)

Solutions

Check the JuiceFS log file (and Windows Event Viewer) for the detailed failure reason logged by the WinFsp host.
Verify WinFsp is installed and its version is compatible; reinstall if the FSD driver is missing.
Review the -o options string passed in conf for syntax or unsupported-option errors.
Confirm the metadata engine is reachable and credentials valid before mounting.
Try mounting to a different drive letter/path to rule out conflicts.

Defensive patterns

Strategy: try-catch

Validate before calling

// PowerShell: verify WinFsp is installed before mounting
if (-not (Get-Service -Name WinFsp.Launcher -ErrorAction SilentlyContinue)) {
    throw 'WinFsp is not installed'
}

Try / catch

if err := mount(); err != nil {
    if strings.Contains(err.Error(), "exit with error") {
        // inspect log file referenced by --log, plus Windows Event Viewer
        log.Fatalf("mount failed; see %s and Event Viewer for the real cause", logPath)
    }
}

Prevention

Install/keep WinFsp up to date before deploying.
Validate the -o options string against supported WinFsp options.
Confirm the metadata engine is reachable before mounting.
Always enable logging so the real cause is captured.

When it happens

Trigger: Any failure inside host.Mount(conf.Mountpoint, ["-o", options]) — bad mount options string, WinFsp driver not installed/running, port/permission problems, or the mounted file system failing during startup — causes exitOk == false.

Common situations: WinFsp not installed or wrong version; invalid -o options passed by the caller; metadata engine unreachable at mount time; another service already holds the drive letter.

Related errors

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