lima-vm/lima · warning

%w: variant mismatch (expected %q, got %q)

Error message

%w: variant mismatch (expected %q, got %q)

What it means

When --image-variant is set, Prepare collects per-image errors instead of failing fast: any image whose Variant differs from the requested targetVariant is recorded as a fileutils.ErrSkipped "variant mismatch" entry. These skipped entries surface if no image matched at all.

Source

Thrown at pkg/instance/start.go:123

		var ensuredImage bool
		var targetVariant, targetArchVariant string
		var targetVariantSet bool
		for _, img := range inst.Config.Images {
			if img.Arch == *inst.Config.Arch {
				targetVariant = img.Variant
				targetArchVariant = img.ArchVariant
				targetVariantSet = true
				break
			}
		}

		if len(inst.Config.Images) == 0 {
			return nil, errors.New("no images are configured (did you set --image-variant or --arch-variant to a value not present in the template?)")
		}
		errs := make([]error, len(inst.Config.Images))
		for i, f := range inst.Config.Images {
			if targetVariantSet && f.Variant != targetVariant {
				errs[i] = fmt.Errorf("%w: variant mismatch (expected %q, got %q)", fileutils.ErrSkipped, targetVariant, f.Variant)
				continue
			}
			if targetVariantSet && f.ArchVariant != targetArchVariant {
				errs[i] = fmt.Errorf("%w: archVariant mismatch (expected %q, got %q)", fileutils.ErrSkipped, targetArchVariant, f.ArchVariant)
				continue
			}
			if _, err := fileutils.DownloadFile(ctx, imagePath, f.File, true, "the image", *inst.Config.Arch, supportedImageFormats); err != nil {
				errs[i] = err
				continue
			}
			if f.Kernel != nil {
				// ensure decompress kernel because vz expects it to be decompressed
				if _, err := fileutils.DownloadFile(ctx, kernel, f.Kernel.File, true, "the kernel", *inst.Config.Arch, nil); err != nil {
					errs[i] = err
					continue
				}
				if f.Kernel.Cmdline != "" {
					if err := os.WriteFile(kernelCmdline, []byte(f.Kernel.Cmdline), 0o644); err != nil {

View on GitHub (pinned to dd909d0973)

Solutions

1. List the template's images to confirm exact variant strings, then pass the matching --image-variant value.
2. Omit --image-variant so the default image is chosen.
3. Edit the instance/template YAML to add an image entry with the wanted variant.
4. Fix the flag casing/spelling - the match is exact string comparison.

Example fix

// before
limactl create template://ubuntu-24.04 --image-variant=desktop
// after
limactl create template://ubuntu-24.04 --image-variant=default

// match your flag against the template's declared variants
var found bool
for _, img := range tmpl.Images {
  if string(img.Variant) == requestedVariant { found = true }
}
if !found { return fmt.Errorf("--image-variant %q not offered by template", requestedVariant) }

When it happens

Trigger: `limactl create/start --image-variant=<v>` where the template's images carry a different Variant field, e.g. requesting 12.04 variant against images tagged with standard/default variants.

Common situations: Mixing image variants across templates (standard, upgrade-only, test variants); scripts hardcoding a variant name that changed between Lima versions; requesting "desktop" on server-only templates.

Related errors

• no images are configured (did you set --image-variant or --a
• %w: archVariant mismatch (expected %q, got %q)
• field `images` must be set
• images[%d].kernel has unexpected architecture %#q, must be %
• images[%d].initrd has unexpected architecture %#q, must be %

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