lima-vm/lima · error

field `arch` must be one of %v; got %#q

Error message

field `arch` must be one of %v; got %#q

What it means

The `arch` field must be one of the architectures Lima supports (x86_64, aarch64, riscv64, armv7l, etc. per limatype.ArchTypes). An invalid or misspelled architecture string fails validation in Validate().

Source

Thrown at pkg/limayaml/validate.go:64

		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"))
	}
	for i, f := range y.Images {
		err := validateFileObject(f.File, fmt.Sprintf("images[%d]", i))

View on GitHub (pinned to dd909d0973)

Solutions

  1. Set `arch` to a supported value such as x86_64 or aarch64
  2. Remove the `arch` line to let Lima default it to the host architecture
  3. Run `limactl template validate` on the file before creating the instance

Example fix

// before
arch: amd64
// after
arch: x86_64
Defensive patterns

Strategy: validation

Validate before calling

func validArch(arch string) bool {
	return slices.Contains(limatype.ArchTypes, limatype.Arch(arch))
}

Type guard

func isSupportedArch(a limatype.Arch) bool {
	return slices.Contains(limatype.ArchTypes, a)
}

Try / catch

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

Prevention

When it happens

Trigger: `arch` set to a value not in limatype.ArchTypes, e.g. `arch: x86`, `arch: amd64`, `arch: ARM64`, or empty string when defaults were not applied.

Common situations: Typos (x86 vs x86_64, amd64 vs x86_64); copying arch names from Docker rather than Lima; hand-merged template edits.

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/17af46913de191dd. Report an issue: GitHub.