field `provision[%d].expression` must not be empty when mode

Error message

field `provision[%d].expression` must not be empty when mode is %#q

What it means

Validate() in pkg/limayaml/validate.go enforces per-mode constraints on each `provision` entry. When a provision script's mode is "yq" (a YAML-modification script), the `expression` field is mandatory because yq mode applies a yq expression to a target file inside the guest. If `expression` is null/unset, validation fails and the config is rejected before the instance can be created, edited, or restarted.

Source

Thrown at pkg/limayaml/validate.go:229

		if *y.OS == limatype.WINDOWS && (p.Mode == limatype.ProvisionModeAnsible || p.Mode == limatype.ProvisionModeBoot || p.Mode == limatype.ProvisionModeYQ) {
			errs = errors.Join(errs, fmt.Errorf("provision mode %#q is not supported on Windows VM", p.Mode))
		}

		// This can lead to fatal Panic if p.Path is nil, better to return an error here
		switch p.Mode {
		case limatype.ProvisionModeData, limatype.ProvisionModeYQ:
			if p.Path == nil {
				errs = errors.Join(errs, fmt.Errorf("field `provision[%d].path` must not be empty when mode is %#q", i, p.Mode))
				return errs
			}
			if !path.IsAbs(*p.Path) {
				errs = errors.Join(errs, fmt.Errorf("field `provision[%d].path` must be an absolute path", i))
			}
			if p.Mode == limatype.ProvisionModeData && p.Content == nil {
				errs = errors.Join(errs, fmt.Errorf("field `provision[%d].content` must not be empty when mode is %#q", i, p.Mode))
			}
			if p.Mode == limatype.ProvisionModeYQ && p.Expression == nil {
				errs = errors.Join(errs, fmt.Errorf("field `provision[%d].expression` must not be empty when mode is %#q", i, p.Mode))
			}
			// FillDefaults makes sure that p.Permissions is not nil
			if _, err := strconv.ParseInt(*p.Permissions, 8, 64); err != nil {
				errs = errors.Join(errs, fmt.Errorf("field `provision[%d].permissions` must be an octal number: %w", i, err))
			}
		default:
			if (p.Script == nil || *p.Script == "") && p.Mode != limatype.ProvisionModeAnsible {
				errs = errors.Join(errs, fmt.Errorf("field `provision[%d].script` must not be empty", i))
			}
			if p.Content != nil {
				errs = errors.Join(errs, fmt.Errorf("field `provision[%d].content` can only be set when mode is %#q", i, limatype.ProvisionModeData))
			}
			if p.Overwrite != nil {
				errs = errors.Join(errs, fmt.Errorf("field `provision[%d].overwrite` can only be set when mode is %#q", i, limatype.ProvisionModeData))
			}
			if p.Owner != nil {
				errs = errors.Join(errs, fmt.Errorf("field `provision[%d].owner` can only be set when mode is %#q", i, limatype.ProvisionModeData))
			}

View on GitHub (pinned to dd909d0973)

Solutions

Add an `expression` field to the provision entry, e.g. `expression: .foo = "bar"`
If the intent was to write a file, use `mode: data` with `content` instead of `mode: yq`
Remove the entry entirely if the yq modification is no longer needed
Run `limactl validate <file>` to confirm the fix before applying

Example fix

# before
provision:
  - mode: yq
    path: /etc/lima.yaml
# after
provision:
  - mode: yq
    path: /etc/lima.yaml
    expression: .cpus = 4

Defensive patterns

Strategy: validation

Validate before calling

// Go: check before calling limayaml.Validate / limactl
for i, p := range cfg.Provision {
    if p.Mode != nil && *p.Mode == limatype.ProvisionModeYQ && p.Expression == nil {
        return fmt.Errorf("provision[%d]: mode yq requires `expression`", i)
    }
}

Type guard

func yqEntryHasExpression(p limatype.Provision) bool {
    return p.Mode == nil || *p.Mode != limatype.ProvisionModeYQ || p.Expression != nil
}

Prevention

Always pair `mode: yq` with both `path` and `expression`
Run `limactl validate config.yaml` in CI before applying templates
Use the JSON/YAML schema when editing configs in an editor
When converting data entries to yq, replace content with expression in the same edit

When it happens

Trigger: A provision entry like `{path: /etc/foo.yaml, mode: yq}` with no `expression` key, passed to limactl create/start/restart, `limactl edit`, `limactl apply` (applyYQExpressionToExistingInstance), or template validation (templateValidateAction/templateArgs).

Common situations: Hand-editing lima.yaml and adding a yq-mode entry but forgetting the expression; converting an existing `data` mode entry to `yq` and deleting content without adding expression; generated templates omitting expression.

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