lima-vm/lima · error

failed to get ISO label: %w

Error message

failed to get ISO label: %w

What it means

checkWindowsVersion (pkg/cidata/template.go:159) reads the ISO label of the previously downloaded Windows ISO (instDir/<ISO>) with iso9660util.Label to distinguish Windows 11 from Windows Server. If the label cannot be read - file missing, not a valid ISO9660 image, or IO error - it wraps the error and template generation aborts.

Source

Thrown at pkg/cidata/template.go:159

func (t *TemplateArgs) generateWindowsInitialPassword() error {
	const pwLen = 16
	// Avoid special characters to minimize potential keyboard layout issue.
	pw, err := password.Generate(pwLen, pwLen/4, 0, false, false)
	if err != nil {
		return fmt.Errorf("failed to generate password: %w", err)
	}

	t.WindowsInitialPassword = pw
	return nil
}

// checkWindowsVersion checks if a guest VM is Windows 11 (true) or Windows server 2025 (false).
func (t *TemplateArgs) checkWindowsVersion(instDir string) error {
	imagePath := filepath.Join(instDir, filenames.ISO)
	label, err := iso9660util.Label(imagePath)
	if err != nil {
		return fmt.Errorf("failed to get ISO label: %w", err)
	}

	t.IsWindowsServer = !strings.HasPrefix(label, windowsClientISOLabelPrefix)

	return nil
}

func ValidateTemplateArgs(args *TemplateArgs) error {
	if err := identifiers.Validate(args.Name); err != nil {
		return err
	}
	// args.User is intentionally not validated here; the user can override with any name they want
	// limayaml.FillDefault will validate the default (local) username, but not an explicit setting
	if args.User == "root" {
		return errors.New("field User must not be `root`")
	}
	if args.UID == 0 {
		return errors.New("field UID must not be 0")

View on GitHub (pinned to dd909d0973)

Solutions

1. Check the ISO exists in the instance directory (~/.lima/<instance>/data-disk.iso or filenames.ISO path)
2. Delete the instance and recreate (`limactl delete` then `limactl start`) to re-download the ISO
3. Verify the downloaded file is a complete ISO (checksum, size)

Example fix

// before (partial download)
$ limactl start windows-instance  # ISO truncated -> Label() fails
// after
$ limactl delete windows-instance
$ limactl start template://experimental/windows-11

isoPath := filepath.Join(instDir, "data-disk.iso") // filenames.ISO
if _, err := os.Stat(isoPath); err != nil {
    return fmt.Errorf("Windows ISO missing, re-download required: %w", err)
}

err := limactl.Start(ctx, instName)
if err != nil && strings.Contains(err.Error(), "failed to get ISO label") {
    log.Printf("ISO unreadable - delete instance and re-download: %v", err)
    // limactl delete <inst> && limactl start again
}

When it happens

Trigger: `limactl start` on a Windows instance when the ISO file is absent from the instance directory, the download was incomplete/corrupted, or the file is not a valid ISO9660 image.

Common situations: Interrupted ISO download, manually deleted instance ISO, or pointing at a partially-written file after a failed/canceled `limactl start`.

Related errors

• --condition=boot is only supported on macOS
• failed to register instance %#q to start at login: %w
• cannot use `--sync` with a wsl2 instance, the host directory
• expected the depth of the converted host working directory (
• unsupported shell %#q for Windows guest, must be one of %v

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