{"record":{"id":"f088e043f26238e3","repo":"lima-vm/lima","slug":"unsupported-shell-q-for-windows-guest-must-be-o","errorCode":null,"errorMessage":"unsupported shell %#q for Windows guest, must be one of %v","messagePattern":"unsupported shell %#q for Windows guest, must be one of (.+?)","errorType":"validation","errorClass":null,"httpStatus":null,"severity":"error","filePath":"cmd/limactl/shell.go","lineNumber":325,"sourceCode":"\tif changeDirCmd == \"\" {\n\t\tchangeDirCmd = \"false\"\n\t}\n\tlogrus.Debugf(\"changeDirCmd=%#q\", changeDirCmd)\n\n\tshell, err := cmd.Flags().GetString(\"shell\")\n\tif err != nil {\n\t\treturn err\n\t}\n\tif *inst.Config.OS == limatype.WINDOWS {\n\t\tif shell == \"\" {\n\t\t\tif inst.Config.User.Shell != nil {\n\t\t\t\tshell = *inst.Config.User.Shell\n\t\t\t} else {\n\t\t\t\tshell = \"cmd.exe\"\n\t\t\t}\n\t\t}\n\t\tif !limayaml.IsSupportedWindowsShell(shell) {\n\t\t\treturn fmt.Errorf(\"unsupported shell %#q for Windows guest, must be one of %v\", shell, limayaml.SupportedWindowsShells)\n\t\t}\n\t} else if shell == \"\" {\n\t\tif inst.Config.User.Shell != nil {\n\t\t\tshell = shellescape.Quote(*inst.Config.User.Shell)\n\t\t} else {\n\t\t\tshell = `\"$SHELL\"`\n\t\t}\n\t} else {\n\t\tshell = shellescape.Quote(shell)\n\t}\n\t// Handle environment variable propagation\n\tvar envPrefix string\n\tpreserveEnv, err := cmd.Flags().GetBool(\"preserve-env\")\n\tif err != nil {\n\t\treturn err\n\t}\n\tif preserveEnv {\n\t\tfilteredEnv := envutil.FilterEnvironment()","sourceCodeStart":307,"sourceCodeEnd":343,"githubUrl":"https://github.com/lima-vm/lima/blob/dd909d0973cd84fa35f9e1693181b4585ea616c1/cmd/limactl/shell.go#L307-L343","documentation":"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.","triggerScenarios":"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`).","commonSituations":"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.","solutions":["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).","Remove the `shell:` field from the instance's lima.yaml so Lima defaults to `cmd.exe` for Windows guests.","Use the exact value from `limayaml.SupportedWindowsShells` as printed by the error message."],"exampleFix":"# lima.yaml (Windows guest)\n# before\nshell: /bin/zsh\n# after\nshell: powershell.exe","handlingStrategy":"validation","validationCode":"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","typeGuard":"null","tryCatchPattern":"if ! limactl shell \"$inst\" --shell \"$sh\" 2>&1 | grep -q 'unsupported shell'; then :; else limactl shell \"$inst\" --shell cmd.exe; fi","preventionTips":["Do not set `shell:` in lima.yaml for Windows guest instances; let Lima default to cmd.exe.","Only use shells from the SupportedWindowsShells list printed by the error.","Beware name variants: use `powershell.exe`/`pwsh.exe`, not `powershell`.","Keep Linux-oriented instance templates separate from Windows ones."],"tags":["cli","limactl","windows","shell","configuration"],"backgroundTag":"unsupported-shell-for-windows-guest","analyzedSha":"dd909d0973cd84fa35f9e1693181b4585ea616c1","analyzedAt":"2026-09-01T14:24:59.842Z","contentChangedAt":null,"schemaVersion":2},"datasetVersion":"2026-09-08T10:18:20.063Z"}