lima-vm/lima · error

failed to create a windows installation marker

Error message

failed to create a windows installation marker

What it means

On Windows guests, the hostagent marks installation completion by creating a marker file (filenames.WinDoneInstallation) in the instance dir; on the next boot Lima skips remounting the OS installer ISO. If os.Create of that marker fails, this plain error is appended to the startup error list.

Source

Thrown at pkg/hostagent/hostagent.go:608

		}
		return nil
	})
	var errs []error

	essentialRequirements := a.essentialRequirements()
	if *a.instConfig.OS == limatype.WINDOWS {
		essentialRequirements = a.essentialWinRequirements()
	}

	if err := a.waitForRequirements("essential", essentialRequirements); err != nil {
		errs = append(errs, err)
	}

	// Windows guest needs a marker file which shows all installation is done.
	// In the next boot, Lima will not mount OS installer ISO file to prevent unexpected re-installation.
	if *a.instConfig.OS == limatype.WINDOWS {
		if _, err := os.Create(filepath.Join(a.instDir, filenames.WinDoneInstallation)); err != nil {
			errs = append(errs, errors.New("failed to create a windows installation marker"))
		}
	}

	if *a.instConfig.SSH.ForwardAgent {
		if *a.instConfig.Plain {
			logrus.Warn("Running in plain mode. Ignoring ssh.forwardAgent")
		} else {
			faScript := `#!/bin/bash
set -eux -o pipefail
ln -sf "${SSH_AUTH_SOCK}" /run/host-services/ssh-auth.sock`
			faDesc := "linking ssh auth socket to static location /run/host-services/ssh-auth.sock"
			stdout, stderr, err := ssh.ExecuteScript(a.instSSHAddress, a.sshLocalPort, a.sshConfig, faScript, faDesc)
			logrus.Debugf("stdout=%#q, stderr=%#q, err=%v", stdout, stderr, err)
			if err != nil {
				errs = append(errs, fmt.Errorf("stdout=%#q, stderr=%#q: %w", stdout, stderr, err))
			}
		}
	}

View on GitHub (pinned to dd909d0973)

Solutions

1. Check permissions on the instance directory (~/.lima/<instance>) and ensure the current user can write to it
2. Free disk space if the volume is full
3. Exclude the .lima directory from antivirus/ransomware protection that may block file creation
4. Re-run 'limactl start'; the error is collected and startup continues, but without the marker the installer ISO may be remounted next boot

// verify instance dir is writable before starting a WINDOWS instance
if *cfg.OS == limatype.WINDOWS {
	probe := filepath.Join(instDir, ".write-probe")
	if err := os.WriteFile(probe, nil, 0o644); err != nil {
		return fmt.Errorf("instance dir not writable: %w", err)
	}
	os.Remove(probe)
}

if err := startHostAgentRoutines(...); err != nil {
	if strings.Contains(err.Error(), "windows installation marker") {
		// check disk space and dir ACLs, then retry
		fixInstanceDirPermissions(instDir)
		return retry(ctx)
	}
	return err
}

When it happens

Trigger: startHostAgentRoutines when instConfig.OS is WINDOWS and os.Create(instDir/WinDoneInstallation) returns an error — permission denied, read-only filesystem, or invalid instance directory.

Common situations: ~/.lima directory owned by another user or locked by AV software on Windows; disk full; instance dir deleted while hostagent is running; running limactl without sufficient permissions on Windows.

Related errors

• failed to register instance %#q to start at login: %w
• failed to create temp file: %w
• failed to write temp plist: %w
• --condition=boot is only supported on macOS
• failed to unregister instance %#q from start at login: %w

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