{"record":{"id":"4441ffff18cd92d4","repo":"lima-vm/lima","slug":"directory-is-unknown-for-the-instance-q","errorCode":null,"errorMessage":"directory is unknown for the instance %#q","messagePattern":"directory is unknown for the instance %#q","errorType":"exception","errorClass":null,"httpStatus":null,"severity":"error","filePath":"pkg/hostagent/hostagent.go","lineNumber":291,"sourceCode":"\t\ta.emitPortForwardEvent(context.Background(), ev)\n\t})\n\ta.portForwarder = newPortForwarder(sshConfig, a.sshAddressPort, rules, ignoreTCP, inst.VMType, func(ev *events.PortForwardEvent) {\n\t\ta.emitPortForwardEvent(context.Background(), ev)\n\t})\n\n\t// Set up vsock event callback if the driver supports it\n\tif vsockEmitter, ok := limaDriver.Driver.(driver.VsockEventEmitter); ok {\n\t\tvsockEmitter.SetVsockEventCallback(func(ev *events.VsockEvent) {\n\t\t\ta.emitVsockEvent(context.Background(), ev)\n\t\t})\n\t}\n\n\treturn a, nil\n}\n\nfunc writeSSHConfigFile(sshPath, instName, instDir, instSSHAddress string, sshLocalPort int, sshOpts []string) error {\n\tif instDir == \"\" {\n\t\treturn fmt.Errorf(\"directory is unknown for the instance %#q\", instName)\n\t}\n\tb := bytes.NewBufferString(`# This SSH config file can be passed to 'ssh -F'.\n# This file is created by Lima, but not used by Lima itself currently.\n# Modifications to this file will be lost on restarting the Lima instance.\n`)\n\tif runtime.GOOS == \"windows\" {\n\t\t// Remove ControlMaster, ControlPath, and ControlPersist options,\n\t\t// because Cygwin-based SSH clients do not support multiplexing when executing commands.\n\t\t// References:\n\t\t//   https://inbox.sourceware.org/cygwin/c98988a5-7e65-4282-b2a1-bb8e350d5fab@acm.org/T/\n\t\t//   https://stackoverflow.com/questions/20959792/is-ssh-controlmaster-with-cygwin-on-windows-actually-possible\n\t\t// By removing these options:\n\t\t//   - Avoids execution failures when the control master is not yet available.\n\t\t//   - Prevents error messages such as:\n\t\t//     > mux_client_request_session: read from master failed: Connection reset by peer\n\t\t//     > ControlSocket ....sock already exists, disabling multiplexing\n\t\t// Only remove these options when writing the SSH config file and executing `limactl shell`, since multiplexing seems to work with port forwarding.\n\t\tsshOpts = sshutil.SSHOptsRemovingControlPath(sshOpts)","sourceCodeStart":273,"sourceCodeEnd":309,"githubUrl":"https://github.com/lima-vm/lima/blob/dd909d0973cd84fa35f9e1693181b4585ea616c1/pkg/hostagent/hostagent.go#L273-L309","documentation":"writeSSHConfigFile refuses to write the instance's SSH config file when instDir is empty, since it cannot know where to place it. This indicates the Instance struct was not fully loaded — the instance directory was not resolved before the hostagent started.","triggerScenarios":"hostagent.New → writeSSHConfigFile with an Instance whose Dir field is empty — typically a programmatically constructed instance, a corrupted/missing instance metadata (lima.yaml in ~/.lima/<name>), or an internal bug resolving the instance dir.","commonSituations":"Partial instance directory after a failed/interrupted 'limactl create'; calling internal APIs without loading the instance via the normal store; manual manipulation of ~/.lima removing instance files.","solutions":["Check that ~/.lima/<instance>/lima.yaml exists and contains valid instance metadata","Recreate the instance: limactl delete <name> && limactl start <name>","If using Lima programmatically, load the instance with the instance store/load helpers so Dir is populated before calling New","Report a bug if a normal limactl start triggers this — it should never happen on a healthy instance"],"exampleFix":null,"handlingStrategy":"validation","validationCode":"// ensure the instance dir resolves before hostagent work\ninstDir := filepath.Join(limaHome, instName)\nst, err := os.Stat(filepath.Join(instDir, \"lima.yaml\"))\nif err != nil || st.IsDir() {\n\treturn fmt.Errorf(\"instance %s missing or incomplete metadata\", instName)\n}","typeGuard":null,"tryCatchPattern":null,"preventionTips":["Always load instances through the official instance-store helpers so Dir is populated","Never manually delete files under ~/.lima/<instance>; use limactl delete","Verify instance integrity after interrupted create/start operations","Report as a bug if limactl start on a healthy instance hits this"],"tags":["ssh","config","instance-directory"],"backgroundTag":"missing-instance-directory","analyzedSha":"dd909d0973cd84fa35f9e1693181b4585ea616c1","analyzedAt":"2026-09-01T14:24:59.842Z","contentChangedAt":null,"schemaVersion":2},"datasetVersion":"2026-09-08T10:18:20.063Z"}