lima-vm/lima · error

field User must not be `root`

Error message

field User must not be `root`

What it means

ValidateTemplateArgs (pkg/cidata/template.go:174) rejects TemplateArgs whose User field is "root". Lima creates a non-root default user in the guest; provisioning as root is unsupported by design, so cloud-config/ISO generation for the instance is refused before anything is written.

Source

Thrown at pkg/cidata/template.go:174

	imagePath := filepath.Join(instDir, filenames.ISO)
	label, err := iso9660util.Label(imagePath)
	if err != nil {
		return fmt.Errorf("failed to get ISO label: %w", err)
	}

	t.IsWindowsServer = !strings.HasPrefix(label, windowsClientISOLabelPrefix)

	return nil
}

func ValidateTemplateArgs(args *TemplateArgs) error {
	if err := identifiers.Validate(args.Name); err != nil {
		return err
	}
	// args.User is intentionally not validated here; the user can override with any name they want
	// limayaml.FillDefault will validate the default (local) username, but not an explicit setting
	if args.User == "root" {
		return errors.New("field User must not be `root`")
	}
	if args.UID == 0 {
		return errors.New("field UID must not be 0")
	}
	if args.Home == "" {
		return errors.New("field Home must be set")
	}
	if args.Shell == "" {
		return errors.New("field Shell must be set")
	}
	if len(args.SSHPubKeys) == 0 {
		return errors.New("field SSHPubKeys must be set")
	}
	for i, m := range args.Mounts {
		f := m.MountPoint
		if !path.IsAbs(f) {
			return fmt.Errorf("field mounts[%d] must be absolute, got %#q", i, f)
		}

View on GitHub (pinned to dd909d0973)

Solutions

1. Remove `user: root` from lima.yaml (or the --user override) and let Lima pick/default the username
2. Set a non-root user name explicitly, e.g. `user: myuser`
3. Use sudo inside the guest for privileged operations instead of a root default user

Example fix

# before
user: root
# after
user: myuser

if args.User == "root" {
    return errors.New("user must not be root; use a regular user and sudo inside the guest")
}

if err := cidata.ValidateTemplateArgs(args); err != nil {
    if strings.Contains(err.Error(), "field User must not be") {
        return fmt.Errorf("set a non-root user in lima.yaml: %w", err)
    }
    return err
}

When it happens

Trigger: Calling GenerateCloudConfig/GenerateISO9660/GenerateWindowsISO (directly or via limactl) with args.User == "root" - typically because lima.yaml sets `user: root` explicitly.

Common situations: Users accustomed to other VM tools setting `user: root` in lima.yaml expecting a root login; scripting instance creation with hardcoded root user.

Related errors

• field UID must not be 0
• field Home must be set
• disk format %#q not supported, use `qcow2` or `raw` instead
• the YAML is invalid, attempted to save the buffer as %#q but
• the YAML is invalid, saved the buffer as %#q: %w

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