What causes "field `cpus` must be set" in lima-vm/lima?

Set `cpus` to a positive integer (e.g. 4)

field `cpus` must be set

Error message

field `cpus` must be set

What it means

The `cpus` field is empty after defaults are applied, so the number of vCPUs for the guest is unknown.

Source

Thrown at pkg/limayaml/validate.go:107

				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))
			}
		}
		if f.Initrd != nil {
			err := validateFileObject(*f.Initrd, fmt.Sprintf("images[%d].initrd", i))
			if err != nil {
				errs = errors.Join(errs, err)
			}
			if f.Initrd.Arch != f.Arch {
				errs = errors.Join(errs, fmt.Errorf("images[%d].initrd has unexpected architecture %#q, must be %#q", i, f.Initrd.Arch, f.Arch))
			}
		}
	}

	if *y.CPUs == 0 {
		errs = errors.Join(errs, errors.New("field `cpus` must be set"))
	}

	if _, err := units.RAMInBytes(*y.Memory); err != nil {
		errs = errors.Join(errs, fmt.Errorf("field `memory` has an invalid value: %w", err))
	}

	if _, err := units.RAMInBytes(*y.Disk); err != nil {
		errs = errors.Join(errs, fmt.Errorf("field `disk` has an invalid value: %w", err))
	}

	for i, disk := range y.AdditionalDisks {
		if err := identifiers.Validate(disk.Name); err != nil {
			errs = errors.Join(errs, fmt.Errorf("field `additionalDisks[%d].name is invalid`: %w", i, err))
		}
	}

	for i, f := range y.Mounts {
		if !filepath.IsAbs(f.Location) && !strings.HasPrefix(f.Location, "~") {

View on GitHub (pinned to dd909d0973)

Solutions

Set `cpus` to a positive integer (e.g. 4)
Remove an explicit `cpus: 0` line and run `limactl create` so defaults apply
When calling Validate() in code, call FillDefault() first

Example fix

// before
cpus: 0
// after
cpus: 4

Defensive patterns

Strategy: validation

Validate before calling

func cpusSet(y *limatype.LimaYAML) bool {
	return y.CPUs != nil && *y.CPUs > 0
}

Try / catch

if err := limayaml.Validate(y, false); err != nil {
	if strings.Contains(err.Error(), "field `cpus` must be set") {
		return fmt.Errorf("cpus must be a positive integer: %w", err)
	}
	return err
}

Prevention

Never set cpus: 0; use a positive value or omit the key
When building LimaYAML in Go, call FillDefault() before Validate()
Check that YAML merges/base templates preserve the cpus key

When it happens

Trigger: `cpus: 0` in the template, or Validate() called on a LimaYAML that skipped FillDefault() so *y.CPUs is still 0.

Common situations: Explicitly setting cpus: 0 to mean "unlimited"; constructing a LimaYAML struct programmatically and calling Validate without defaults; YAML merge losing the cpus key.

Understand the failure class

Background: "missing required argument" and "the following required arguments were not provided": what required-argument errors mean and how to fix them — this error's family across 20 libraries.

Related errors

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