{"record":{"id":"660749d34084ec66","repo":"juicedata/juicefs","slug":"cannot-mount-to-a-local-directory-when-as-local","errorCode":null,"errorMessage":"Cannot mount to a local directory when --as-local-volume is not set","messagePattern":"Cannot mount to a local directory when --as-local-volume is not set","errorType":"validation","errorClass":null,"httpStatus":null,"severity":"error","filePath":"pkg/winfsp/winfs.go","lineNumber":1172,"sourceCode":"\tif winfspDbgLog != \"\" {\n\t\tlogger.Infof(\"WinFsp Debug Log Path: %s\", winfspDbgLog)\n\t\toptions += \",debug,DebugLog=\" + winfspDbgLog\n\t}\n\tif flushOnCleanup {\n\t\toptions += \",FlushOnCleanup=1\"\n\t}\n\n\thost.SetCapCaseInsensitive(!caseSensitive)\n\thost.SetCapReaddirPlus(true)\n\n\tmountVolumeName := filepath.VolumeName(conf.Mountpoint)\n\tmountPointIsDrive := isDriveByVolumeName(conf.Mountpoint)\n\tif mountPointIsDrive {\n\t\tconf.Mountpoint = mountVolumeName\n\t}\n\n\tif !mountPointIsDrive && mountAsNetworkDrive {\n\t\treturn fmt.Errorf(\"Cannot mount to a local directory when --as-local-volume is not set\")\n\t}\n\n\tif !mountPointIsDrive {\n\t\tif _, err := os.Stat(conf.Mountpoint); err == nil {\n\t\t\treturn fmt.Errorf(\"Mount point %s cannot be an existing folder\", conf.Mountpoint)\n\t\t}\n\n\t\t// the parent directory of the mount point must exist\n\t\tparentDir := filepath.Dir(conf.Mountpoint)\n\t\tif _, err := os.Stat(parentDir); os.IsNotExist(err) {\n\t\t\treturn fmt.Errorf(\"Parent directory %s of mount point %s does not exist\", parentDir, conf.Mountpoint)\n\t\t}\n\t}\n\n\tlogger.Debugf(\"mount point: %s, mountPointIsDrive: %v, options: %s\", conf.Mountpoint, mountPointIsDrive, options)\n\texitOk := host.Mount(conf.Mountpoint, []string{\"-o\", options})\n\tif exitOk {\n\t\treturn nil","sourceCodeStart":1154,"sourceCodeEnd":1190,"githubUrl":"https://github.com/juicedata/juicefs/blob/c9a67b23e8e08ec23ec331aa6f1675e2319e921c/pkg/winfsp/winfs.go#L1154-L1190","documentation":"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.","triggerScenarios":"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.","commonSituations":"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.","solutions":["Use a free drive letter as the mountpoint (e.g. Z:) instead of a directory path.","Add --as-local-volume to mount onto a local directory path.","Update automation/scripts targeting Windows to use drive letters or the flag.","Check the resolved mountpoint: ensure isDriveByVolumeName logic matches the format you pass (e.g. 'Z:' vs 'Z:\\')."],"exampleFix":"// before\njuicefs mount sqlite3://test.db C:\\jfs\n// after\njuicefs mount sqlite3://test.db C:\\jfs --as-local-volume\n# or\njuicefs mount sqlite3://test.db Z:","handlingStrategy":"validation","validationCode":"// PowerShell: validate mountpoint before invoking juicefs\n$mp = 'C:\\jfs'\n$isDrive = $mp -match '^[A-Za-z]:$'\nif (-not $isDrive -and -not ($args -contains '--as-local-volume')) {\n    throw \"Use a drive letter or pass --as-local-volume for $mp\"\n}","typeGuard":null,"tryCatchPattern":"out, err := exec.Command(\"juicefs\", \"mount\", meta, mp).CombinedOutput()\nif err != nil && strings.Contains(string(out), \"--as-local-volume\") {\n    out, err = exec.Command(\"juicefs\", \"mount\", meta, mp, \"--as-local-volume\").CombinedOutput()\n}","preventionTips":["On Windows prefer drive letters as mountpoints.","Always pass --as-local-volume when mounting into a directory.","Do not copy Unix mount paths verbatim to Windows scripts.","Read the mountpoint validation rules before automating mounts."],"tags":["windows","winfsp","mount","cli"],"backgroundTag":"invalid-config-value","analyzedSha":"c9a67b23e8e08ec23ec331aa6f1675e2319e921c","analyzedAt":"2026-09-06T17:55:48.476Z","contentChangedAt":"2026-09-06T17:55:48.476Z","schemaVersion":2},"datasetVersion":"2026-09-14T00:17:10.932Z"}