{"record":{"id":"b93af1fc38ddd512","repo":"lima-vm/lima","slug":"failed-to-create-hard-link-from-q-to-q-w","errorCode":null,"errorMessage":"failed to create hard link from %#q to %#q: %w","messagePattern":"failed to create hard link from %#q to %#q: %w","errorType":"error_code","errorClass":null,"httpStatus":null,"severity":"error","filePath":"pkg/driver/vz/vm_darwin.go","lineNumber":979,"sourceCode":"\t\tlogrus.Debugf(\"Client network file GC'ed\")\n\t})\n\tvmNetworkFiles = append(vmNetworkFiles, server, client)\n\treturn server, client, nil\n}\n\nfunc ensureIPSW(instDir string) error {\n\tipsw := filepath.Join(instDir, filenames.ImageIPSW)\n\tif osutil.FileExists(ipsw) {\n\t\treturn nil\n\t}\n\tipswBase := filepath.Join(instDir, filenames.Image)\n\tif _, err := os.Stat(ipswBase); err != nil {\n\t\treturn err\n\t}\n\t// The installer wants the file to have \".ipsw\" suffix.\n\t// The link is created as a hard link, as the installer does not accept symlinks.\n\tif err := os.Link(ipswBase, ipsw); err != nil {\n\t\treturn fmt.Errorf(\"failed to create hard link from %#q to %#q: %w\", ipswBase, ipsw, err)\n\t}\n\treturn nil\n}\n","sourceCodeStart":961,"sourceCodeEnd":983,"githubUrl":"https://github.com/lima-vm/lima/blob/dd909d0973cd84fa35f9e1693181b4585ea616c1/pkg/driver/vz/vm_darwin.go#L961-L983","documentation":"ensureIPSW creates a hard link from the cached .ipsw base file to the expected .ipsw path (the installer requires the .ipsw suffix and rejects symlinks). This error wraps os.Link failure — typically the destination already exists or the source/destination is unusable.","triggerScenarios":"os.Link(ipswBase, ipsw) fails during macOS guest setup, e.g. because the destination hard link already exists (EEXIST from a previous partial run), or the source file vanished between the preceding os.Stat and the Link call.","commonSituations":"Interrupted previous installation leaving a stale link at the destination; read-only or full filesystem; the IPSW cache file in LIMA_HOME deleted between stat and link; permission problems in ~/.lima.","solutions":["Delete the stale destination file/link at the reported ipsw path and retry the operation","Remove the partially-created instance (`limactl delete <instance> --force`) and recreate it","Check disk space and permissions on the LIMA_HOME directory","Verify the cached .ipsw base file still exists and is on a filesystem supporting hard links"],"exampleFix":"// before\n$ limactl start macos-test\n// failed: failed to create hard link from ... to ...\n// after\n$ limactl delete macos-test --force\n$ limactl start macos-test","handlingStrategy":"validation","validationCode":"if _, err := os.Stat(ipsw); err == nil {\n    os.Remove(ipsw) // clear stale hard link before starting\n}\nif _, err := os.Stat(ipswBase); err != nil {\n    return fmt.Errorf(\"cached ipsw missing: %w\", err)\n}","typeGuard":null,"tryCatchPattern":"if err := start(); err != nil && strings.Contains(err.Error(), \"failed to create hard link\") {\n    os.Remove(ipswPath) // then retry start\n}","preventionTips":["Avoid killing `limactl start` mid-install; use `limactl stop`","Keep adequate free disk space in LIMA_HOME","Keep the ~/.lima cache directory on a normal local filesystem (hard-link capable)","Force-delete half-created instances before retrying"],"tags":["filesystem","ipsw","macos-guest","vz"],"backgroundTag":"hard-link-creation-failed","analyzedSha":"dd909d0973cd84fa35f9e1693181b4585ea616c1","analyzedAt":"2026-09-01T14:24:59.842Z","contentChangedAt":null,"schemaVersion":2},"datasetVersion":"2026-09-08T10:18:20.063Z"}