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

Error message

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

What it means

A provision entry with mode `data` exists to create/overwrite a file, so it must carry the file body in the `content` field. `limayaml.Validate` rejects a data-mode entry whose `content` is nil, since without content Lima would have nothing to write and the entry is meaningless.

Source

Thrown at pkg/limayaml/validate.go:226

				i, limatype.ProvisionModeDependency))
		}

		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))
			}

View on GitHub (pinned to dd909d0973)

Solutions

Add a `content` key with the desired file body (use a YAML block scalar `|` for multi-line content).
If the file body should come from an external source, pre-render it into the template or use a script-mode provision with curl/heredoc instead.
If the entry was only meant to modify an existing file, consider mode: yq with an expression, but keep content if full replacement is intended.

Example fix

# before
- mode: data
  path: /etc/motd
# after
- mode: data
  path: /etc/motd
  content: |
    Welcome to Lima.

Defensive patterns

Strategy: validation

Validate before calling

for i, p := range cfg.Provision {
	if p.Mode == "data" && p.Content == nil {
		return fmt.Errorf("provision[%d]: mode data requires content", i)
	}
}

Type guard

func hasDataContent(p limatype.Provision) bool {
	return p.Mode != limatype.ProvisionModeData || p.Content != nil
}

Try / catch

if err := limayaml.Validate(y, false, "config.yaml"); err != nil {
	if strings.Contains(err.Error(), "`content` must not be empty when mode is") {
		return fmt.Errorf("add content (or switch mode) for the data provision entry: %w", err)
	}
	return err
}

Prevention

Use a YAML block scalar (content: |) so multi-line bodies parse correctly.
Check indentation after edits: a de-indented block scalar silently becomes null.
Run limactl template validate in CI for every template, catching missing content before VM creation.

When it happens

Trigger: Any command that invokes limayaml.Validate (limactl create/start/edit/restart/apply/clone/rename/template validate/template args) on a YAML with `provision: - mode: data path: /some/file` and no `content:` key (or content explicitly null).

Common situations: Converting a script-mode entry to mode: data and forgetting to add content; YAML multiline block scalar mis-indented so content parses as null; an anchor overriding content to empty; expecting content to be fetched from file/URL (Lima requires embedded content in this mode).

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