lima-vm/lima · error

unknown provision mode %#q

Error message

unknown provision mode %#q

What it means

appendProvisionEntries (pkg/cidata/cidata.go:580) walks the instance's provision entries and only knows certain modes (script, task/YQ, ansible-skip, etc.). If a Provision.Mode value is not one of the recognized limatype.ProvisionMode constants, it returns this error instead of silently ignoring the entry.

Source

Thrown at pkg/cidata/cidata.go:580

		// Boot commands are not treated as script files in cidata.iso.
		// Instead of that, they are stored in TemplateArgs.BootCmds then embedded in bootCmd field in user-data.
		// For Windows VM, there is no boot step where we can run commands.
		case limatype.ProvisionModeBoot:
			continue
		case limatype.ProvisionModeData:
			layout = append(layout, iso9660util.Entry{
				Path:   fmt.Sprintf("provision.%s/%08d", f.Mode, i),
				Reader: strings.NewReader(*f.Content),
			})
		case limatype.ProvisionModeYQ:
			layout = append(layout, iso9660util.Entry{
				Path:   fmt.Sprintf("provision.%s/%08d", f.Mode, i),
				Reader: strings.NewReader(*f.Expression),
			})
		case limatype.ProvisionModeAnsible:
			continue
		default:
			return nil, fmt.Errorf("unknown provision mode %#q", f.Mode)
		}
	}

	return layout, nil
}

func GenerateWindowsISO(ctx context.Context, instDir, name string, instConfig *limatype.LimaYAML, udpDNSLocalPort, tcpDNSLocalPort, vsockPort int, virtioPort string, noCloudInit, rosettaEnabled, rosettaBinFmt bool) (string, error) {
	args, err := templateArgs(ctx, true, instDir, name, instConfig, udpDNSLocalPort, tcpDNSLocalPort, vsockPort, virtioPort, noCloudInit, rosettaEnabled, rosettaBinFmt)
	if err != nil {
		return "", err
	}

	if err := ValidateTemplateArgs(args); err != nil {
		return "", err
	}

	// The generated password is used only for an initial setup.
	// After that, the password is overwritten.

View on GitHub (pinned to dd909d0973)

Solutions

1. Check the `mode:` field of every provision entry in lima.yaml
2. Use a valid mode: "system", "user", "boot", or remove the mode field to use the default
3. Validate the config with `limactl validate <file>` before starting

Example fix

# before
provision:
  - mode: scripts
    path: setup.sh
# after
provision:
  - mode: system
    path: setup.sh

validModes := map[string]bool{"": true, "system": true, "user": true, "boot": true}
for _, p := range cfg.Provision {
    if !validModes[p.Mode] {
        return fmt.Errorf("unsupported provision mode %q", p.Mode)
    }
}

err := limactl.Start(ctx, instName)
if err != nil && strings.Contains(err.Error(), "unknown provision mode") {
    log.Fatalf("fix provision.mode in lima.yaml: %v", err)
}

When it happens

Trigger: A lima.yaml `provision` entry has a `mode:` string that is not a valid provision mode constant (misspelled e.g. `mode: scripts`, `mode: ansible-playbook`, or hand-written YAML with an arbitrary mode).

Common situations: Typo in provision mode, editing YAML by hand without schema validation, or a config written for a newer/older Lima version using a mode this build does not know.

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

• field `provision[%d].expression` must not be empty when mode
• field `provision[%d].permissions` must be an octal number: %
• field `provision[%d].script` must not be empty
• field `provision[%d].content` can only be set when mode is %
• field `provision[%d].overwrite` can only be set when mode is

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