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.

Solutions

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

Defensive patterns

Strategy: validation

Validate before calling

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

Try / catch

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
}

Prevention

Ensure your user owns ~/.lima and subdirectories (icacls on Windows)
Exclude .lima from antivirus controlled-folder access
Keep free disk space headroom on the instance volume
Don't delete instance files while a VM is running

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

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

Appendix: 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)