{"record":{"id":"4a7acadd656e03d7","repo":"lima-vm/lima","slug":"failed-to-create-a-windows-installation-marker","errorCode":null,"errorMessage":"failed to create a windows installation marker","messagePattern":"failed to create a windows installation marker","errorType":"exception","errorClass":null,"httpStatus":null,"severity":"error","filePath":"pkg/hostagent/hostagent.go","lineNumber":608,"sourceCode":"\t\t}\n\t\treturn nil\n\t})\n\tvar errs []error\n\n\tessentialRequirements := a.essentialRequirements()\n\tif *a.instConfig.OS == limatype.WINDOWS {\n\t\tessentialRequirements = a.essentialWinRequirements()\n\t}\n\n\tif err := a.waitForRequirements(\"essential\", essentialRequirements); err != nil {\n\t\terrs = append(errs, err)\n\t}\n\n\t// Windows guest needs a marker file which shows all installation is done.\n\t// In the next boot, Lima will not mount OS installer ISO file to prevent unexpected re-installation.\n\tif *a.instConfig.OS == limatype.WINDOWS {\n\t\tif _, err := os.Create(filepath.Join(a.instDir, filenames.WinDoneInstallation)); err != nil {\n\t\t\terrs = append(errs, errors.New(\"failed to create a windows installation marker\"))\n\t\t}\n\t}\n\n\tif *a.instConfig.SSH.ForwardAgent {\n\t\tif *a.instConfig.Plain {\n\t\t\tlogrus.Warn(\"Running in plain mode. Ignoring ssh.forwardAgent\")\n\t\t} else {\n\t\t\tfaScript := `#!/bin/bash\nset -eux -o pipefail\nln -sf \"${SSH_AUTH_SOCK}\" /run/host-services/ssh-auth.sock`\n\t\t\tfaDesc := \"linking ssh auth socket to static location /run/host-services/ssh-auth.sock\"\n\t\t\tstdout, stderr, err := ssh.ExecuteScript(a.instSSHAddress, a.sshLocalPort, a.sshConfig, faScript, faDesc)\n\t\t\tlogrus.Debugf(\"stdout=%#q, stderr=%#q, err=%v\", stdout, stderr, err)\n\t\t\tif err != nil {\n\t\t\t\terrs = append(errs, fmt.Errorf(\"stdout=%#q, stderr=%#q: %w\", stdout, stderr, err))\n\t\t\t}\n\t\t}\n\t}","sourceCodeStart":590,"sourceCodeEnd":626,"githubUrl":"https://github.com/lima-vm/lima/blob/dd909d0973cd84fa35f9e1693181b4585ea616c1/pkg/hostagent/hostagent.go#L590-L626","documentation":"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.","triggerScenarios":"startHostAgentRoutines when instConfig.OS is WINDOWS and os.Create(instDir/WinDoneInstallation) returns an error — permission denied, read-only filesystem, or invalid instance directory.","commonSituations":"~/.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.","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"],"exampleFix":null,"handlingStrategy":"validation","validationCode":"// verify instance dir is writable before starting a WINDOWS instance\nif *cfg.OS == limatype.WINDOWS {\n\tprobe := filepath.Join(instDir, \".write-probe\")\n\tif err := os.WriteFile(probe, nil, 0o644); err != nil {\n\t\treturn fmt.Errorf(\"instance dir not writable: %w\", err)\n\t}\n\tos.Remove(probe)\n}","typeGuard":null,"tryCatchPattern":"if err := startHostAgentRoutines(...); err != nil {\n\tif strings.Contains(err.Error(), \"windows installation marker\") {\n\t\t// check disk space and dir ACLs, then retry\n\t\tfixInstanceDirPermissions(instDir)\n\t\treturn retry(ctx)\n\t}\n\treturn err\n}","preventionTips":["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"],"tags":["windows","filesystem","marker-file"],"backgroundTag":"file-create-permission-denied","analyzedSha":"dd909d0973cd84fa35f9e1693181b4585ea616c1","analyzedAt":"2026-09-01T14:24:59.842Z","contentChangedAt":null,"schemaVersion":2},"datasetVersion":"2026-09-08T10:18:20.063Z"}