lima-vm/lima · error

field Home must be set

Error message

field Home must be set

What it means

ValidateTemplateArgs (pkg/cidata/template.go:180) requires TemplateArgs.Home to be a non-empty string, since the guest user's home directory is required by the cloud-config user-data and boot templates. An empty Home aborts generation before any templates execute.

Source

Thrown at pkg/cidata/template.go:180

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

func ExecuteTemplateCloudConfig(args *TemplateArgs) ([]byte, error) {
	if err := ValidateTemplateArgs(args); err != nil {

View on GitHub (pinned to dd909d0973)

Solutions

1. Set args.Home to the guest home path (conventionally "/home/<user>.linux") before generation
2. Run limayaml.FillDefault so Home is derived automatically
3. For ExecuteTemplateCloudConfig callers, populate all required fields: Name, User, UID, Home, Shell, SSHPubKeys

Example fix

// before
args := &cidata.TemplateArgs{Name: inst.Name, User: "myuser", UID: 1000}
// after
args := &cidata.TemplateArgs{Name: inst.Name, User: "myuser", UID: 1000, Home: "/home/myuser.linux"}

if args.Home == "" {
    return errors.New("TemplateArgs.Home must be set (e.g. /home/<user>.linux)")
}

if err := cidata.ValidateTemplateArgs(args); err != nil {
    if strings.Contains(err.Error(), "field Home must be set") {
        return fmt.Errorf("set Home before cidata generation: %w", err)
    }
    return err
}

When it happens

Trigger: Calling GenerateCloudConfig/GenerateISO9660/GenerateWindowsISO or ExecuteTemplateCloudConfig with TemplateArgs.Home == "" - typically when TemplateArgs is built manually without setting Home.

Common situations: Custom tooling or tests constructing TemplateArgs directly and forgetting Home; code paths that bypass limayaml.FillDefault, which normally derives Home from the user name.

Related errors

• field User must not be `root`
• field UID must not be 0
• 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/c61e96aeb2f3fc35. Report an issue: GitHub.