lima-vm/lima · error

unsupported image type for %s: %q. %s only supports importin

Error message

unsupported image type for %s: %q. %s only supports importing tar archive root filesystems, not standard VM disk images

What it means

WSL2 instances import the guest root filesystem from a tar archive, not a VM disk image. When an image location matches the unsupportedVMImgRegex (standard VM disk images like .qcow2/.iso/.vhd), validation returns this error naming the vmType and location.

Source

Thrown at pkg/driver/wsl2/wsl_driver_windows.go:137

	if cfg.TPM != nil && *cfg.TPM {
		return errors.New("field `tpm` is not supported on WSL2 driver")
	}

	if cfg.VMType != nil {
		if cfg.Images != nil && cfg.Arch != nil {
			// TODO: real filetype checks
			tarFileRegex := regexp.MustCompile(`\.(tar|tgz|txz|tbz2|tzst|tar\.(gz|xz|bz2|zstd|zst))$`)
			unsupportedVMImgRegex := regexp.MustCompile(`\.(qcow2|raw|img|iso|ipsw)(\.(gz|xz|bz2|zstd|zst))?$`)
			squashfsRegex := regexp.MustCompile(`\.squashfs(\.(gz|xz|bz2|zstd|zst))?$`)
			for i, image := range cfg.Images {
				if unknown := reflectutil.UnknownNonEmptyFields(image, "File", "Variant", "ArchVariant"); len(unknown) > 0 {
					logrus.Warnf("Ignoring: vmType %s: images[%d]: %+v", *cfg.VMType, i, unknown)
				}
				if image.Arch == *cfg.Arch {
					location := image.Location
					if !tarFileRegex.MatchString(location) {
						if unsupportedVMImgRegex.MatchString(location) {
							return fmt.Errorf("unsupported image type for %s: %q. %s only supports importing tar archive root filesystems, not standard VM disk images", *cfg.VMType, location, *cfg.VMType)
						}
						if squashfsRegex.MatchString(location) {
							return fmt.Errorf("unsupported image type for %s: %q. %s does not natively support importing SquashFS images; please convert the image to a tar archive before importing", *cfg.VMType, location, *cfg.VMType)
						}
						return fmt.Errorf("unsupported image type for %s: %q. A tar archive root filesystem (.tar, .tar.gz, .tar.xz, etc.) is required", *cfg.VMType, location)
					}
				}
			}
		}

		if cfg.Mounts != nil {
			for i, mount := range cfg.Mounts {
				if unknown := reflectutil.UnknownNonEmptyFields(mount); len(unknown) > 0 {
					logrus.Warnf("Ignoring: vmType %s: mounts[%d]: %+v", *cfg.VMType, i, unknown)
				}
			}
		}

View on GitHub (pinned to dd909d0973)

Solutions

  1. Replace the image with a tar-archive rootfs (.tar, .tar.gz, .tar.xz, etc.) for the target distro
  2. Use a distro image known to work with WSL2 imports (e.g. an Ubuntu WSL rootfs tarball)
  3. Keep separate templates for wsl2 vs qemu instead of sharing image URLs

Example fix

# before
images:
  - location: https://cloud-images.ubuntu.com/noble/current/noble-server-cloudimg-amd64.img
# after
images:
  - location: https://cloud-images.ubuntu.com/wsl/releases/noble/current/ubuntu-noble-wsl-amd64-ubuntu24.04lts.rootfs.tar.gz
Defensive patterns

Strategy: validation

Validate before calling

var tarRe = regexp.MustCompile(`\.(tar|tgz|txz|tbz2|tzst|tar\.(gz|xz|bz2|zstd|zst))$`)
func imagesAreTarRootfs(cfg *limatype.LimaYAML) bool {
	if cfg.Images == nil { return true }
	for _, img := range cfg.Images {
		if !tarRe.MatchString(img.Location) { return false }
	}
	return true
}

Type guard

func isTarRootfs(location string) bool {
	var tarRe = regexp.MustCompile(`\.(tar|tgz|txz|tbz2|tzst|tar\.(gz|xz|bz2|zstd|zst))$`)
	return tarRe.MatchString(location)
}

Try / catch

if err := driver.Configure(ctx, cfg); err != nil {
	if strings.Contains(err.Error(), "only supports importing tar archive") {
		// swap image URL for a WSL rootfs tarball, then retry
	}
	return err
}

Prevention

When it happens

Trigger: An images[] entry whose Location is for the matching arch and whose filename looks like a VM disk image (not matching tarFileRegex, but matching unsupportedVMImgRegex), during wsl2 config validation.

Common situations: Pointing `images[].location` at a cloud image .qcow2 or .iso download (typical for QEMU) while using wsl2; reusing a QEMU template's image URLs on Windows.

Related errors

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