What causes "unsupported arch: %#q" in lima-vm/lima?

Remove the explicit `arch:` field so Lima defaults to the native architecture

unsupported arch: %#q

Error message

unsupported arch: %#q

What it means

validateConfig rejects CPU architectures that do not match the native host architecture, since WSL2 cannot run foreign-architecture guests. The message interpolates the offending arch value with %#q. It is a hard config error returned before instance creation.

Source

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

	if cfg == nil {
		return errors.New("configuration is nil")
	}
	if cfg.MountType != nil && *cfg.MountType != limatype.WSLMount {
		return fmt.Errorf("field `mountType` must be %#q for WSL2 driver, got %#q", limatype.WSLMount, *cfg.MountType)
	}
	// TODO: revise this list for WSL2
	if cfg.VMType != nil {
		if unknown := reflectutil.UnknownNonEmptyFields(cfg, knownYamlProperties...); len(unknown) > 0 {
			logrus.Warnf("Ignoring: vmType %s: %+v", *cfg.VMType, unknown)
		}
	}

	if cfg.OS != nil && *cfg.OS == limatype.WINDOWS {
		return errors.New("currently Windows guest OS is only supported on QEMU")
	}

	if !limatype.IsNativeArch(*cfg.Arch) {
		return fmt.Errorf("unsupported arch: %#q", *cfg.Arch)
	}

	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

View on GitHub (pinned to dd909d0973)

Solutions

Remove the explicit `arch:` field so Lima defaults to the native architecture
Set `arch:` to the host architecture (e.g. x86_64 on typical Windows PCs)
Use a driver that supports emulation (e.g. qemu with Rosetta/TCG) if a foreign arch is required

Example fix

# before (on x86_64 host)
arch: aarch64
vmType: wsl2
# after
arch: x86_64
vmType: wsl2

Defensive patterns

Strategy: validation

Validate before calling

import "github.com/lima-vm/lima/v2/pkg/limatype"
func validArchForWSL2(cfg *limatype.LimaYAML) bool {
	return cfg.Arch == nil || limatype.IsNativeArch(*cfg.Arch)
}
// check before handing cfg to the wsl2 driver

Type guard

func isForeignArch(cfg *limatype.LimaYAML) bool {
	return cfg.Arch != nil && !limatype.IsNativeArch(*cfg.Arch)
}

Try / catch

if err := driver.Configure(ctx, cfg); err != nil {
	if strings.Contains(err.Error(), "unsupported arch:") {
		cfg.Arch = nil // let Lima default to native arch, retry
		return driver.Configure(ctx, cfg)
	}
	return err
}

Prevention

Omit the arch field unless you specifically need it
Match arch to the host when targeting wsl2
Validate templates on every target host architecture in CI

When it happens

Trigger: A lima.yaml with `arch: aarch64` (or x86_64/arm64 mismatching the host) passed to the wsl2 driver, when limatype.IsNativeArch(*cfg.Arch) returns false. Hit via Configure, Validate, or limactl create/start.

Common situations: Copying a config made for an ARM machine onto an x86_64 Windows box (or vice versa); explicit arch pinning in templates; CI machines with a different arch than the developer's config.

Related errors

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