abiosoft/colima · critical

error picking an available port: %w

Error message

error picking an available port: %w

What it means

RandomAvailablePort (util/util.go:29) binds a TCP listener on :0 to obtain a kernel-assigned ephemeral port and calls logrus.Fatal on failure — the process exits, the error is not returned. net.Listen("tcp", ":0") fails when the host cannot bind any socket: file-descriptor exhaustion, ephemeral port range exhaustion, or a sandbox denying bind. colima uses this when wiring forwarded ports for the VM, so it typically hits during colima start.

Source

Thrown at util/util.go:29

	"github.com/google/shlex"
	"github.com/sirupsen/logrus"
)

// HomeDir returns the user home directory.
func HomeDir() string {
	home, err := os.UserHomeDir()
	if err != nil {
		// this should never happen
		logrus.Fatal(fmt.Errorf("error retrieving home directory: %w", err))
	}
	return home
}

// RandomAvailablePort returns an available port on the host machine.
func RandomAvailablePort() int {
	listener, err := net.Listen("tcp", ":0")
	if err != nil {
		logrus.Fatal(fmt.Errorf("error picking an available port: %w", err))
	}

	if err := listener.Close(); err != nil {
		logrus.Fatal(fmt.Errorf("error closing temporary port listener: %w", err))
	}

	return listener.Addr().(*net.TCPAddr).Port
}

// isPortAvailable checks if a specific port is available on the host.
func isPortAvailable(port int) bool {
	listener, err := net.Listen("tcp", fmt.Sprintf(":%d", port))
	if err != nil {
		return false
	}
	if err := listener.Close(); err != nil {
		return false
	}

View on GitHub (pinned to c3a5f9184d)

Solutions

1. Raise the fd limit: `ulimit -n 4096` (or LimitNOFILE= in the service unit) and retry
2. Reduce socket churn / wait out TIME_WAIT, or tune the ephemeral port range (sysctl net.ipv4.ip_local_port_range)
3. Stop unneeded VMs/port-forwards (`colima stop`, prune docker networks) to release sockets
4. If sandboxed, grant network-bind access or run outside the sandbox

Example fix

# before
$ colima start
FATA[0000] error picking an available port: ...: too many open files

# after
$ ulimit -n 4096
$ colima start

// probe socket-creation ability before the fatal path
if l, err := net.Listen("tcp", "127.0.0.1:0"); err != nil {
    log.Fatalf("cannot bind sockets (check ulimit -n / sandbox): %v", err)
} else { _ = l.Close() }

// util.RandomAvailablePort exits on failure; if you need resilience,
// implement your own picker and retry with backoff:
for attempt := 0; attempt < 3; attempt++ {
    if l, err := net.Listen("tcp", ":0"); err == nil {
        port := l.Addr().(*net.TCPAddr).Port
        _ = l.Close()
        return port
    }
    time.Sleep(200 * time.Millisecond)
}

When it happens

Trigger: ulimit -n reached because Lima/QEMU processes and port forwards hold many fds; net.ipv4.ip_local_port_range exhausted by thousands of TIME_WAIT sockets; running under a seatbelt/sandbox profile that blocks network bind; a container started with --network none.

Common situations: Long-running hosts with many colima instances/forwards; load tests opening massive numbers of sockets; restricted CI sandboxes; misconfigured launchd sandboxes on macOS.

Related errors

• no available port found in range %d-%d
• port %d is already in use
• error closing temporary port listener: %w
• error provisioning %s: %w
• gateway %q is not IPv4

AI-assisted analysis of abiosoft/colima@c3a5f9184d (2026-08-15). Data as JSON: /api/errors/fd5642a2256885dd. Report an issue: GitHub.