lima-vm/lima · error

invalid ssh local port %d

Error message

invalid ssh local port %d

What it means

determineSSHLocalPort validates the configured ssh.localPort: a positive value is used as-is, zero means auto-pick, but a negative value is rejected outright as invalid. This is a config sanity check before any port allocation is attempted.

Source

Thrown at pkg/hostagent/hostagent.go:327

		sshOpts = sshutil.SSHOptsRemovingControlPath(sshOpts)
	}
	if err := sshutil.Format(b, sshPath, instName, sshutil.FormatConfig,
		append(sshOpts,
			fmt.Sprintf("Hostname=%s", instSSHAddress),
			fmt.Sprintf("Port=%d", sshLocalPort),
		)); err != nil {
		return err
	}
	fileName := filepath.Join(instDir, filenames.SSHConfig)
	return os.WriteFile(fileName, b.Bytes(), 0o600)
}

func determineSSHLocalPort(confLocalPort int, instName, limaVersion string) (int, error) {
	if confLocalPort > 0 {
		return confLocalPort, nil
	}
	if confLocalPort < 0 {
		return 0, fmt.Errorf("invalid ssh local port %d", confLocalPort)
	}
	if versionutil.LessThan(limaVersion, "2.0.0") && instName == "default" {
		// use hard-coded value for "default" instance, for backward compatibility
		return 60022, nil
	}
	sshLocalPort, err := freeport.TCP()
	if err != nil {
		return 0, fmt.Errorf("failed to find a free port, try setting `ssh.localPort` manually: %w", err)
	}
	return sshLocalPort, nil
}

func (a *HostAgent) emitEvent(_ context.Context, ev events.Event) {
	a.eventEncMu.Lock()
	defer a.eventEncMu.Unlock()

	a.statusMu.Lock()
	a.currentStatus = ev.Status

View on GitHub (pinned to dd909d0973)

Solutions

1. Set ssh.localPort to a positive port (e.g. 60022) or remove the key entirely to let Lima auto-select a free port
2. Fix the value in ~/.lima/<instance>/lima.yaml or the source template
3. Run 'limactl validate' on the config before starting

Example fix

// before (lima.yaml)
ssh:
  localPort: -1
// after
ssh:
  localPort: 60022

// guard the configured port before starting
if conf, ok := sshCfg["localPort"].(int); ok && conf < 0 {
	return fmt.Errorf("ssh.localPort must be >= 0, got %d", conf)
}

When it happens

Trigger: Starting an instance whose config (lima.yaml ssh.localPort or stored instance config) contains a negative SSH local port value, via limactl start → hostagent.New → determineSSHLocalPort.

Common situations: Typo in ssh.localPort (e.g. -2222); template variable substitution yielding a negative number; a migration or hand-edit writing a sentinel negative value that older Lima versions tolerated.

Related errors

• port not found in %#q
• the YAML is invalid, saved the buffer as %#q: %w
• field `vmOpts.qemu.minimumVersion` must be a semvar value, g
• field `mountType` must be %#q for WSL2 driver, got %#q
• failed to validate the instance YAML after filling defaults:

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