lima-vm/lima · error

directory is unknown for the instance %#q

Error message

directory is unknown for the instance %#q

What it means

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.

Source

Thrown at pkg/hostagent/hostagent.go:291

		a.emitPortForwardEvent(context.Background(), ev)
	})
	a.portForwarder = newPortForwarder(sshConfig, a.sshAddressPort, rules, ignoreTCP, inst.VMType, func(ev *events.PortForwardEvent) {
		a.emitPortForwardEvent(context.Background(), ev)
	})

	// Set up vsock event callback if the driver supports it
	if vsockEmitter, ok := limaDriver.Driver.(driver.VsockEventEmitter); ok {
		vsockEmitter.SetVsockEventCallback(func(ev *events.VsockEvent) {
			a.emitVsockEvent(context.Background(), ev)
		})
	}

	return a, nil
}

func writeSSHConfigFile(sshPath, instName, instDir, instSSHAddress string, sshLocalPort int, sshOpts []string) error {
	if instDir == "" {
		return fmt.Errorf("directory is unknown for the instance %#q", instName)
	}
	b := bytes.NewBufferString(`# This SSH config file can be passed to 'ssh -F'.
# This file is created by Lima, but not used by Lima itself currently.
# Modifications to this file will be lost on restarting the Lima instance.
`)
	if runtime.GOOS == "windows" {
		// Remove ControlMaster, ControlPath, and ControlPersist options,
		// because Cygwin-based SSH clients do not support multiplexing when executing commands.
		// References:
		//   https://inbox.sourceware.org/cygwin/c98988a5-7e65-4282-b2a1-bb8e350d5fab@acm.org/T/
		//   https://stackoverflow.com/questions/20959792/is-ssh-controlmaster-with-cygwin-on-windows-actually-possible
		// By removing these options:
		//   - Avoids execution failures when the control master is not yet available.
		//   - Prevents error messages such as:
		//     > mux_client_request_session: read from master failed: Connection reset by peer
		//     > ControlSocket ....sock already exists, disabling multiplexing
		// Only remove these options when writing the SSH config file and executing `limactl shell`, since multiplexing seems to work with port forwarding.
		sshOpts = sshutil.SSHOptsRemovingControlPath(sshOpts)

View on GitHub (pinned to dd909d0973)

Solutions

1. Check that ~/.lima/<instance>/lima.yaml exists and contains valid instance metadata
2. Recreate the instance: limactl delete <name> && limactl start <name>
3. If using Lima programmatically, load the instance with the instance store/load helpers so Dir is populated before calling New
4. Report a bug if a normal limactl start triggers this — it should never happen on a healthy instance

// ensure the instance dir resolves before hostagent work
instDir := filepath.Join(limaHome, instName)
st, err := os.Stat(filepath.Join(instDir, "lima.yaml"))
if err != nil || st.IsDir() {
	return fmt.Errorf("instance %s missing or incomplete metadata", instName)
}

When it happens

Trigger: 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.

Common situations: 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.

Related errors

• invalid ssh local port %d
• port not found in %#q
• the YAML is invalid, saved the buffer as %#q: %w
• network %#q already exists
• failed to resolve vm for %#q: %w

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