{"record":{"id":"c9b6c5a6c8459d82","repo":"lima-vm/lima","slug":"unsupported-image-type-for-s-q-a-tar-archive-r","errorCode":null,"errorMessage":"unsupported image type for %s: %q. A tar archive root filesystem (.tar, .tar.gz, .tar.xz, etc.) is required","messagePattern":"unsupported image type for (.+?): %q\\. A tar archive root filesystem \\(\\.tar, \\.tar\\.gz, \\.tar\\.xz, etc\\.\\) is required","errorType":"validation","errorClass":null,"httpStatus":null,"severity":"error","filePath":"pkg/driver/wsl2/wsl_driver_windows.go","lineNumber":142,"sourceCode":"\t\tif cfg.Images != nil && cfg.Arch != nil {\n\t\t\t// TODO: real filetype checks\n\t\t\ttarFileRegex := regexp.MustCompile(`\\.(tar|tgz|txz|tbz2|tzst|tar\\.(gz|xz|bz2|zstd|zst))$`)\n\t\t\tunsupportedVMImgRegex := regexp.MustCompile(`\\.(qcow2|raw|img|iso|ipsw)(\\.(gz|xz|bz2|zstd|zst))?$`)\n\t\t\tsquashfsRegex := regexp.MustCompile(`\\.squashfs(\\.(gz|xz|bz2|zstd|zst))?$`)\n\t\t\tfor i, image := range cfg.Images {\n\t\t\t\tif unknown := reflectutil.UnknownNonEmptyFields(image, \"File\", \"Variant\", \"ArchVariant\"); len(unknown) > 0 {\n\t\t\t\t\tlogrus.Warnf(\"Ignoring: vmType %s: images[%d]: %+v\", *cfg.VMType, i, unknown)\n\t\t\t\t}\n\t\t\t\tif image.Arch == *cfg.Arch {\n\t\t\t\t\tlocation := image.Location\n\t\t\t\t\tif !tarFileRegex.MatchString(location) {\n\t\t\t\t\t\tif unsupportedVMImgRegex.MatchString(location) {\n\t\t\t\t\t\t\treturn 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)\n\t\t\t\t\t\t}\n\t\t\t\t\t\tif squashfsRegex.MatchString(location) {\n\t\t\t\t\t\t\treturn 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)\n\t\t\t\t\t\t}\n\t\t\t\t\t\treturn fmt.Errorf(\"unsupported image type for %s: %q. A tar archive root filesystem (.tar, .tar.gz, .tar.xz, etc.) is required\", *cfg.VMType, location)\n\t\t\t\t\t}\n\t\t\t\t}\n\t\t\t}\n\t\t}\n\n\t\tif cfg.Mounts != nil {\n\t\t\tfor i, mount := range cfg.Mounts {\n\t\t\t\tif unknown := reflectutil.UnknownNonEmptyFields(mount); len(unknown) > 0 {\n\t\t\t\t\tlogrus.Warnf(\"Ignoring: vmType %s: mounts[%d]: %+v\", *cfg.VMType, i, unknown)\n\t\t\t\t}\n\t\t\t}\n\t\t}\n\n\t\tif cfg.Networks != nil {\n\t\t\tfor i, network := range cfg.Networks {\n\t\t\t\tif unknown := reflectutil.UnknownNonEmptyFields(network); len(unknown) > 0 {\n\t\t\t\t\tlogrus.Warnf(\"Ignoring: vmType %s: networks[%d]: %+v\", *cfg.VMType, i, unknown)\n\t\t\t\t}","sourceCodeStart":124,"sourceCodeEnd":160,"githubUrl":"https://github.com/lima-vm/lima/blob/dd909d0973cd84fa35f9e1693181b4585ea616c1/pkg/driver/wsl2/wsl_driver_windows.go#L124-L160","documentation":"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.","triggerScenarios":"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.","commonSituations":"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.","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"],"exampleFix":"# before\nimages:\n  - location: ./rootfs.bin\n# after\n# convert: tar -C rootfs-dir -czf rootfs.tar.gz .\nimages:\n  - location: ./rootfs.tar.gz","handlingStrategy":"validation","validationCode":"var tarRe = regexp.MustCompile(`\\.(tar|tgz|txz|tbz2|tzst|tar\\.(gz|xz|bz2|zstd|zst))$`)\nfunc ensureRecognizedRootfs(cfg *limatype.LimaYAML) error {\n\tif cfg.Images == nil { return nil }\n\tfor _, img := range cfg.Images {\n\t\tif !tarRe.MatchString(img.Location) {\n\t\t\treturn fmt.Errorf(\"image %q must be a tar rootfs\", img.Location)\n\t\t}\n\t}\n\treturn nil\n}","typeGuard":"func hasRecognizedArchiveExtension(location string) bool {\n\tvar tarRe = regexp.MustCompile(`\\.(tar|tgz|txz|tbz2|tzst|tar\\.(gz|xz|bz2|zstd|zst))$`)\n\treturn tarRe.MatchString(location)\n}","tryCatchPattern":"if err := driver.Configure(ctx, cfg); err != nil {\n\tif strings.Contains(err.Error(), \"tar archive root filesystem\") {\n\t\t// rename/convert the artifact to .tar.(gz|xz|...) and retry\n\t}\n\treturn err\n}","preventionTips":["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"],"tags":["wsl2","image-format","config-validation"],"backgroundTag":"unsupported-image-format","analyzedSha":"dd909d0973cd84fa35f9e1693181b4585ea616c1","analyzedAt":"2026-09-01T14:24:59.842Z","contentChangedAt":null,"schemaVersion":2},"datasetVersion":"2026-09-08T10:18:20.063Z"}