lima-vm/lima · error

cannot use `--sync` when the instance has host mounts config

Error message

cannot use `--sync` when the instance has host mounts configured, start the instance with `--mount-none` to disable mounts

What it means

`limactl shell --sync` copies the host working directory into the guest with rsync instead of relying on a shared filesystem mount. Lima rejects the flag when the instance still has host mounts configured in its lima.yaml, because the two mechanisms would expose the same host files through two different paths and defeat the isolation `--sync` is meant to provide. The check happens up front in shellAction before any SSH or rsync work starts.

Source

Thrown at cmd/limactl/shell.go:214

			// fresh master can be established.
			removed, rmErr := sshutil.RemoveStaleControlMaster(ctx, inst.Dir)
			if rmErr != nil {
				return rmErr
			}
			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 {

View on GitHub (pinned to dd909d0973)

Solutions

1. Recreate or restart the instance with mounts disabled: `limactl stop <instance>` then `limactl start --mount-none <instance>` (or remove the `mounts:` entries from the lima.yaml before starting).
2. If you actually want the host files visible, drop the `--sync` flag and rely on the existing mounts instead.
3. Verify with `limactl list <instance>` / the instance's lima.yaml that `mounts` is empty before retrying.

Example fix

# before
limactl shell default --sync .
# after
limactl stop default
limactl start --mount-none default
limactl shell default --sync .

if [ -n "$LIMA_MOUNTS" ]; then echo 'start instance with --mount-none before using --sync'; fi
# or check config: yq '.mounts | length == 0' ~/.lima/<instance>/lima.yaml

null

if ! limactl shell "$inst" --sync . 2>err.txt; then grep -q 'mount-none' err.txt && echo 'recreate instance with: limactl start --mount-none' || cat err.txt; fi

When it happens

Trigger: Running `limactl shell <instance> --sync <dir>` (or with --sync pointing at the current directory) against an instance whose config has a non-empty `mounts:` list, i.e. the instance was started without `--mount-none`.

Common situations: A developer wants to stop sharing host files into the guest but forgets that the instance was created with default mounts (the default template mounts the home directory); they add `--sync` to the shell command while the instance still runs with mounts enabled.

Related errors

• cannot use `--sync` with a wsl2 instance, the host directory
• 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
• cannot use `--workdir` and `--sync` at the same time

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