lima-vm/lima · error

unsupported shell %#q for Windows guest, must be one of %v

Error message

unsupported shell %#q for Windows guest, must be one of %v

What it means

When the guest OS is Windows, the shell used for `limactl shell` must be one of Lima's supported Windows shells (e.g. cmd.exe, powershell.exe, pwsh.exe, bash). shellAction resolves the shell from the `--shell` flag or the instance config's `user.shell`, and if the resulting value is not in `limayaml.SupportedWindowsShells` it aborts, because command quoting and flags differ per Windows shell.

Source

Thrown at cmd/limactl/shell.go:325

	if changeDirCmd == "" {
		changeDirCmd = "false"
	}
	logrus.Debugf("changeDirCmd=%#q", changeDirCmd)

	shell, err := cmd.Flags().GetString("shell")
	if err != nil {
		return err
	}
	if *inst.Config.OS == limatype.WINDOWS {
		if shell == "" {
			if inst.Config.User.Shell != nil {
				shell = *inst.Config.User.Shell
			} else {
				shell = "cmd.exe"
			}
		}
		if !limayaml.IsSupportedWindowsShell(shell) {
			return fmt.Errorf("unsupported shell %#q for Windows guest, must be one of %v", shell, limayaml.SupportedWindowsShells)
		}
	} else if shell == "" {
		if inst.Config.User.Shell != nil {
			shell = shellescape.Quote(*inst.Config.User.Shell)
		} else {
			shell = `"$SHELL"`
		}
	} else {
		shell = shellescape.Quote(shell)
	}
	// Handle environment variable propagation
	var envPrefix string
	preserveEnv, err := cmd.Flags().GetBool("preserve-env")
	if err != nil {
		return err
	}
	if preserveEnv {
		filteredEnv := envutil.FilterEnvironment()

View on GitHub (pinned to dd909d0973)

Solutions

1. Pass a supported shell explicitly: `--shell cmd.exe`, `--shell powershell.exe`, `--shell pwsh.exe`, or an allowed bash variant (see the list printed in the error).
2. Remove the `shell:` field from the instance's lima.yaml so Lima defaults to `cmd.exe` for Windows guests.
3. Use the exact value from `limayaml.SupportedWindowsShells` as printed by the error message.

Example fix

# lima.yaml (Windows guest)
# before
shell: /bin/zsh
# after
shell: powershell.exe

os=$(limactl list --json | jq -r "select(.name==\"$inst\") | .os"); if [ "$os" = "windows" ] && [ -n "$SHELL_FLAG" ]; then case "$SHELL_FLAG" in cmd.exe|powershell.exe|pwsh.exe|bash) ;; *) echo "unsupported windows shell: $SHELL_FLAG"; exit 1;; esac; fi

null

if ! limactl shell "$inst" --shell "$sh" 2>&1 | grep -q 'unsupported shell'; then :; else limactl shell "$inst" --shell cmd.exe; fi

When it happens

Trigger: Running `limactl shell <windows-guest-instance> --shell <name>` with an unsupported name, or the instance's `user.shell` in lima.yaml is set to something not in the supported list (e.g. `/bin/zsh`, `fish`, `tcsh`).

Common situations: Copying a Linux instance's lima.yaml (`shell: /bin/bash`) to a Windows guest; typos like `powershell` vs `powershell.exe`; assuming any guest shell binary works as it does on Linux guests.

Related errors

• cannot use `--sync` with a wsl2 instance, the host directory
• expected the depth of the converted host working directory (
• 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

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