failed to find a free port, try setting `ssh.localPort` manu

Error message

failed to find a free port, try setting `ssh.localPort` manually: %w

What it means

When ssh.localPort is 0 (or unset for non-legacy instances), Lima asks freeport.TCP() for an available local TCP port. If no free port can be found, this error is returned, advising the user to pin ssh.localPort manually.

Source

Thrown at pkg/hostagent/hostagent.go:335

	}
	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
	a.statusMu.Unlock()

	if ev.Time.IsZero() {
		ev.Time = time.Now()
	}
	if err := a.eventEnc.Encode(ev); err != nil {
		logrus.WithField("event", ev).WithError(err).Error("failed to emit an event")
	}

View on GitHub (pinned to dd909d0973)

Solutions

Set an explicit port in the config: ssh.localPort: <free-port> (e.g. 60022), ensuring nothing else binds it
Free up ports: close idle VMs/connections or widen the local ephemeral port range (net.ipv4.ip_local_port_range on Linux)
Check for security software or network policies intercepting local binds
Retry after transient exhaustion — free port availability often recovers once connections close

Example fix

// before (lima.yaml)
ssh: {}
// after
ssh:
  localPort: 60022

Defensive patterns

Strategy: validation

Validate before calling

// confirm a usable local port exists before starting
l, err := net.Listen("tcp", "127.0.0.1:0")
if err != nil {
	return fmt.Errorf("no local ports available: %w", err)
}
l.Close()

Try / catch

if strings.Contains(err.Error(), "failed to find a free port") {
	// pin a known-free port and retry once
	inst.Config.SSH.LocalPort = limayaml.PointInt(60022)
	return startInstance(ctx, inst)
}

Prevention

Set an explicit ssh.localPort when running many instances or in restricted sandboxes
Monitor ephemeral port usage; widen net.ipv4.ip_local_port_range if often exhausted
Avoid running security software that intercepts local bind attempts
Close idle Lima instances to release reserved ports

When it happens

Trigger: limactl start on an instance where the SSH local port must be auto-selected and freeport.TCP fails — typically because no ports are available in its scan range.

Common situations: Exhausted ephemeral port range from many open connections/VMs; firewall or security software blocking bind probes; restrictive container/network namespaces limiting available ports; running thousands of Lima instances concurrently.

Related errors

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