What causes "field `user.shell` must be an absolute path, got %#q" in lima-vm/lima?

Use the full absolute guest path, e.g. /bin/zsh or /usr/bin/fish

field `user.shell` must be an absolute path, got %#q

Error message

field `user.shell` must be an absolute path, got %#q

What it means

For non-Windows guests (linux, darwin, freebsd), the optional `user.shell` must be an absolute path (e.g. /bin/bash). Relative paths like `bash` fail validation because Lima passes the shell path to the guest directly. Checked in Validate().

Source

Thrown at pkg/limayaml/validate.go:74

		}
		if !slices.Contains([]limatype.Arch{limatype.X8664, limatype.AARCH64}, *y.Arch) {
			errs = errors.Join(errs, fmt.Errorf("currently Windows guest is only supported on [%#q, %#q]; got %#q", limatype.X8664, limatype.AARCH64, *y.Arch))
		}
	default:
		errs = errors.Join(errs, fmt.Errorf("field `os` must be one of %#q; got %#q", limatype.OSTypes, *y.OS))
	}
	if !slices.Contains(limatype.ArchTypes, *y.Arch) {
		errs = errors.Join(errs, fmt.Errorf("field `arch` must be one of %v; got %#q", limatype.ArchTypes, *y.Arch))
	}

	if y.User.Shell != nil {
		shell := *y.User.Shell
		if *y.OS == limatype.WINDOWS {
			if !IsSupportedWindowsShell(shell) {
				errs = errors.Join(errs, fmt.Errorf("field `user.shell` must be one of %v for Windows guest, got %#q", SupportedWindowsShells, shell))
			}
		} else if !path.IsAbs(shell) {
			errs = errors.Join(errs, fmt.Errorf("field `user.shell` must be an absolute path, got %#q", shell))
		}
	}

	if len(y.Images) == 0 {
		errs = errors.Join(errs, errors.New("field `images` must be set"))
	}
	for i, f := range y.Images {
		err := validateFileObject(f.File, fmt.Sprintf("images[%d]", i))
		if err != nil {
			errs = errors.Join(errs, err)
		}
		if f.Kernel != nil {
			err := validateFileObject(f.Kernel.File, fmt.Sprintf("images[%d].kernel", i))
			if err != nil {
				errs = errors.Join(errs, err)
			}
			if f.Kernel.Arch != f.Arch {
				errs = errors.Join(errs, fmt.Errorf("images[%d].kernel has unexpected architecture %#q, must be %#q", i, f.Kernel.Arch, f.Arch))

View on GitHub (pinned to dd909d0973)

Solutions

Use the full absolute guest path, e.g. /bin/zsh or /usr/bin/fish
Remove `user.shell` to use the guest default
Verify the shell binary exists at that path in the guest image

Example fix

// before
user:
  shell: zsh
// after
user:
  shell: /bin/zsh

Defensive patterns

Strategy: validation

Validate before calling

func validShellPath(os, shell string) bool {
	return os == "windows" || shell == "" || path.IsAbs(shell)
}

Try / catch

if err := limayaml.Validate(y, false); err != nil {
	if strings.Contains(err.Error(), "must be an absolute path") {
		return fmt.Errorf("shell must be absolute: %w", err)
	}
	return err
}

Prevention

Always write the full guest path like /bin/bash, never a bare command name
Resolve the binary with `command -v zsh` inside a similar guest to find the path
Prefer omitting user.shell unless a non-default shell is required

When it happens

Trigger: `user.shell` set to a bare command name ("bash", "zsh") or a relative path ("./bin/sh") while os is not windows.

Common situations: Users accustomed to $SHELL names write `shell: zsh`; templates copied from dotfiles configs.

Related errors

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