unsupported image type for %s: %q. A tar archive root filesy

Error message

unsupported image type for %s: %q. A tar archive root filesystem (.tar, .tar.gz, .tar.xz, etc.) is required

What it means

Fallback image-format error for wsl2: the image is neither a tar archive nor a recognized disk/squashfs type, so it cannot be used as a rootfs. The tarFileRegex check failed and neither specialized regex matched, so validation returns this generic tar requirement message.

Source

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

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

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

View on GitHub (pinned to dd909d0973)

Solutions

Rename/convert the image to a recognized tar format: .tar, .tgz, .txz, .tbz2, .tzst, or .tar.(gz|xz|bz2|zst)
Re-download a proper WSL-compatible rootfs tarball
Check the URL with `curl -sIL <url>` to confirm what the file actually is

Example fix

# before
images:
  - location: ./rootfs.bin
# after
# convert: tar -C rootfs-dir -czf rootfs.tar.gz .
images:
  - location: ./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 ensureRecognizedRootfs(cfg *limatype.LimaYAML) error {
	if cfg.Images == nil { return nil }
	for _, img := range cfg.Images {
		if !tarRe.MatchString(img.Location) {
			return fmt.Errorf("image %q must be a tar rootfs", img.Location)
		}
	}
	return nil
}

Type guard

func hasRecognizedArchiveExtension(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(), "tar archive root filesystem") {
		// rename/convert the artifact to .tar.(gz|xz|...) and retry
	}
	return err
}

Prevention

Always package custom rootfs as .tar.gz/.tar.xz with a proper extension
Check `file` output or HTTP content-type of the image before use
Keep image naming conventions consistent across your fleet

When it happens

Trigger: An images[] entry for the matching arch whose location lacks any recognized archive/disk extension (e.g. no extension, .zip, .raw) while vmType is wsl2.

Common situations: Naming a tarball with a wrong or missing extension, using a .zip-packaged rootfs, or pointing at a build artifact that isn't a rootfs at all.

Related errors

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