lima-vm/lima · error

field `os` must be one of %#q; got %#q

Error message

field `os` must be one of %#q; got %#q

What it means

The `os` field must be one of the supported guest OS types (linux, darwin, freebsd, windows). Any other value (typo, unsupported OS, empty string surviving defaults) fails validation. Thrown by Validate() in pkg/limayaml/validate.go during all template-consuming actions.

Source

Thrown at pkg/limayaml/validate.go:61

		}
		// Unparsable version.Version (like commit hashes or "<unknown>") is treated as "latest/greatest"
		// and will pass all version comparisons, allowing development builds to work.
		if !versionutil.GreaterEqual(version.Version, *y.MinimumLimaVersion) {
			errs = errors.Join(errs, fmt.Errorf("template requires Lima version %#q; this is only %#q", *y.MinimumLimaVersion, version.Version))
		}
	}

	switch *y.OS {
	case limatype.LINUX, limatype.DARWIN, limatype.FREEBSD:
	case limatype.WINDOWS:
		if *y.VMType != limatype.QEMU {
			errs = errors.Join(errs, fmt.Errorf("currently Windows guest is only supported on %#q; got %#q", limatype.QEMU, *y.VMType))
		}
		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"))

View on GitHub (pinned to dd909d0973)

Solutions

  1. Set `os` to one of: linux, darwin, freebsd, windows
  2. Remove the `os` line to accept the default (linux)
  3. Run `limactl template validate <file>` to check before create

Example fix

// before
os: linuz
// after
os: linux
Defensive patterns

Strategy: validation

Validate before calling

func validOS(os string) bool {
	return slices.Contains(limatype.OSTypes, limatype.OS(os))
}

Type guard

func isSupportedOS(os string) bool {
	for _, t := range limatype.OSTypes {
		if string(t) == os { return true }
	}
	return false
}

Try / catch

if err := limayaml.Validate(y, false); err != nil {
	if strings.Contains(err.Error(), "field `os` must be one of") {
		return fmt.Errorf("fix the os field: %w", err)
	}
	return err
}

Prevention

When it happens

Trigger: `os` in the lima.yaml is set to a value not in limatype.OSTypes, e.g. `os: windows11`, `os: win`, or a misspelling like `os: linuz`.

Common situations: Typos when hand-editing templates; copying `os` values from other tools; forgetting that guest OS differs from host OS.

Understand the failure class

Background: Invalid enum value errors: "Unknown type", "Invalid scope", "must be one of" — when a string is not on the library's allowed list — this error's family across 23 libraries.

Related errors

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