lima-vm/lima · error

cannot use `--sync` with a wsl2 instance, the host directory

Error message

cannot use `--sync` with a wsl2 instance, the host directory is already visible in the guest

What it means

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.

Source

Thrown at cmd/limactl/shell.go:219

			if !removed {
				return err
			}
			logrus.WithError(err).Warnf("Removed stale ssh control socket for the instance %#q after the master had already exited", instName)
		}
	}

	syncDirVal, err := flags.GetString("sync")
	if err != nil {
		return fmt.Errorf("failed to get sync flag: %w", err)
	}
	syncHostWorkdir := syncDirVal != ""
	if syncHostWorkdir && len(inst.Config.Mounts) > 0 {
		return errors.New("cannot use `--sync` when the instance has host mounts configured, start the instance with `--mount-none` to disable mounts")
	}
	// A wsl2 guest already reaches the host directory through the /mnt automount,
	// so `--sync` cannot isolate it from host files the way it does elsewhere.
	if syncHostWorkdir && inst.VMType == limatype.WSL2 {
		return errors.New("cannot use `--sync` with a wsl2 instance, the host directory is already visible in the guest")
	}

	// When workDir is explicitly set, the shell MUST have workDir as the cwd, or exit with an error.
	//
	// changeDirCmd := "cd workDir || exit 1"                  if workDir != ""
	//              := "cd hostCurrentDir || cd hostHomeDir"   if workDir == ""
	var changeDirCmd string
	// hostCurrentDirNative is the path as the host sees it. hostCurrentDir is the
	// form the guest and the copy tool receive, which on Windows differs.
	var hostCurrentDir, hostCurrentDirNative string
	if syncDirVal != "" {
		hostCurrentDirNative, err = filepath.Abs(syncDirVal)
	} else {
		hostCurrentDirNative, err = os.Getwd()
	}
	if err == nil {
		hostCurrentDir = hostCurrentDirNative
		if runtime.GOOS == "windows" {

View on GitHub (pinned to dd909d0973)

Solutions

1. Omit `--sync` and access the host directory via the WSL2 `/mnt/...` automount path inside the guest.
2. If you need the isolation `--sync` provides, use a non-WSL2 VM type (e.g. QEMU or VZ on Windows/macOS).

Example fix

# before
limactl shell wsl2-instance --sync .
# after
limactl shell wsl2-instance   # cd into /mnt/c/... inside the guest

vmtype=$(limactl list --json | jq -r "select(.name==\"$inst\") | .vmType"); [ "$vmtype" = "wsl2" ] && echo 'do not use --sync with wsl2'

null

null

When it happens

Trigger: Running `limactl shell <wsl2-instance> --sync <dir>` on any instance whose VM type is wsl2, regardless of mounts configuration.

Common situations: 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.

Related errors

• cannot use `--sync` when the instance has host mounts config
• failed to determine the host directory to sync: %w
• rsync is required for `--sync` but not found: %w
• expected the depth of the host working directory (%#q) to be
• expected the depth of the converted host working directory (

AI-assisted analysis of lima-vm/lima@dd909d0973 (2026-09-01). Data as JSON: /api/errors/9f1f3d1941f96fbc. Report an issue: GitHub.