{"record":{"id":"9f1f3d1941f96fbc","repo":"lima-vm/lima","slug":"cannot-use-sync-with-a-wsl2-instance-the-host","errorCode":null,"errorMessage":"cannot use `--sync` with a wsl2 instance, the host directory is already visible in the guest","messagePattern":"cannot use `--sync` with a wsl2 instance, the host directory is already visible in the guest","errorType":"validation","errorClass":null,"httpStatus":null,"severity":"error","filePath":"cmd/limactl/shell.go","lineNumber":219,"sourceCode":"\t\t\tif !removed {\n\t\t\t\treturn err\n\t\t\t}\n\t\t\tlogrus.WithError(err).Warnf(\"Removed stale ssh control socket for the instance %#q after the master had already exited\", instName)\n\t\t}\n\t}\n\n\tsyncDirVal, err := flags.GetString(\"sync\")\n\tif err != nil {\n\t\treturn fmt.Errorf(\"failed to get sync flag: %w\", err)\n\t}\n\tsyncHostWorkdir := syncDirVal != \"\"\n\tif syncHostWorkdir && len(inst.Config.Mounts) > 0 {\n\t\treturn errors.New(\"cannot use `--sync` when the instance has host mounts configured, start the instance with `--mount-none` to disable mounts\")\n\t}\n\t// A wsl2 guest already reaches the host directory through the /mnt automount,\n\t// so `--sync` cannot isolate it from host files the way it does elsewhere.\n\tif syncHostWorkdir && inst.VMType == limatype.WSL2 {\n\t\treturn errors.New(\"cannot use `--sync` with a wsl2 instance, the host directory is already visible in the guest\")\n\t}\n\n\t// When workDir is explicitly set, the shell MUST have workDir as the cwd, or exit with an error.\n\t//\n\t// changeDirCmd := \"cd workDir || exit 1\"                  if workDir != \"\"\n\t//              := \"cd hostCurrentDir || cd hostHomeDir\"   if workDir == \"\"\n\tvar changeDirCmd string\n\t// hostCurrentDirNative is the path as the host sees it. hostCurrentDir is the\n\t// form the guest and the copy tool receive, which on Windows differs.\n\tvar hostCurrentDir, hostCurrentDirNative string\n\tif syncDirVal != \"\" {\n\t\thostCurrentDirNative, err = filepath.Abs(syncDirVal)\n\t} else {\n\t\thostCurrentDirNative, err = os.Getwd()\n\t}\n\tif err == nil {\n\t\thostCurrentDir = hostCurrentDirNative\n\t\tif runtime.GOOS == \"windows\" {","sourceCodeStart":201,"sourceCodeEnd":237,"githubUrl":"https://github.com/lima-vm/lima/blob/dd909d0973cd84fa35f9e1693181b4585ea616c1/cmd/limactl/shell.go#L201-L237","documentation":"On WSL2 the guest already sees host directories through the automatic `/mnt/<drive>` automount, so `--sync`'s purpose — isolating the guest shell from host files by syncing only the working directory — cannot work there. Lima rejects the combination in shellAction before doing any rsync work.","triggerScenarios":"Running `limactl shell <wsl2-instance> --sync <dir>` on any instance whose VM type is wsl2, regardless of mounts configuration.","commonSituations":"A developer using Lima on Windows with the WSL2 backend follows documentation or muscle memory from QEMU/VZ usage and adds `--sync`, not realizing WSL2 exposes the host filesystem via /mnt automatically.","solutions":["Omit `--sync` and access the host directory via the WSL2 `/mnt/...` automount path inside the guest.","If you need the isolation `--sync` provides, use a non-WSL2 VM type (e.g. QEMU or VZ on Windows/macOS)."],"exampleFix":"# before\nlimactl shell wsl2-instance --sync .\n# after\nlimactl shell wsl2-instance   # cd into /mnt/c/... inside the guest","handlingStrategy":"validation","validationCode":"vmtype=$(limactl list --json | jq -r \"select(.name==\\\"$inst\\\") | .vmType\"); [ \"$vmtype\" = \"wsl2\" ] && echo 'do not use --sync with wsl2'","typeGuard":"null","tryCatchPattern":"null","preventionTips":["Skip --sync in scripts when the VM type is wsl2; use /mnt/<drive> paths instead.","Document per-backend shell flags in team runbooks.","Detect the backend once at setup time and store it, rather than probing each run."],"tags":["cli","limactl","wsl2","sync","windows"],"backgroundTag":"unsupported-flag-for-backend","analyzedSha":"dd909d0973cd84fa35f9e1693181b4585ea616c1","analyzedAt":"2026-09-01T14:24:59.842Z","contentChangedAt":null,"schemaVersion":2},"datasetVersion":"2026-09-08T10:18:20.063Z"}