{"record":{"id":"fd5642a2256885dd","repo":"abiosoft/colima","slug":"error-picking-an-available-port-w","errorCode":null,"errorMessage":"error picking an available port: %w","messagePattern":"error picking an available port: %w","errorType":"console","errorClass":null,"httpStatus":null,"severity":"critical","filePath":"util/util.go","lineNumber":29,"sourceCode":"\t\"github.com/google/shlex\"\n\t\"github.com/sirupsen/logrus\"\n)\n\n// HomeDir returns the user home directory.\nfunc HomeDir() string {\n\thome, err := os.UserHomeDir()\n\tif err != nil {\n\t\t// this should never happen\n\t\tlogrus.Fatal(fmt.Errorf(\"error retrieving home directory: %w\", err))\n\t}\n\treturn home\n}\n\n// RandomAvailablePort returns an available port on the host machine.\nfunc RandomAvailablePort() int {\n\tlistener, err := net.Listen(\"tcp\", \":0\")\n\tif err != nil {\n\t\tlogrus.Fatal(fmt.Errorf(\"error picking an available port: %w\", err))\n\t}\n\n\tif err := listener.Close(); err != nil {\n\t\tlogrus.Fatal(fmt.Errorf(\"error closing temporary port listener: %w\", err))\n\t}\n\n\treturn listener.Addr().(*net.TCPAddr).Port\n}\n\n// isPortAvailable checks if a specific port is available on the host.\nfunc isPortAvailable(port int) bool {\n\tlistener, err := net.Listen(\"tcp\", fmt.Sprintf(\":%d\", port))\n\tif err != nil {\n\t\treturn false\n\t}\n\tif err := listener.Close(); err != nil {\n\t\treturn false\n\t}","sourceCodeStart":11,"sourceCodeEnd":47,"githubUrl":"https://github.com/abiosoft/colima/blob/c3a5f9184d83a197184f897a9f07eb3c01b3bc88/util/util.go#L11-L47","documentation":"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.","triggerScenarios":"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.","commonSituations":"Long-running hosts with many colima instances/forwards; load tests opening massive numbers of sockets; restricted CI sandboxes; misconfigured launchd sandboxes on macOS.","solutions":["Raise the fd limit: `ulimit -n 4096` (or LimitNOFILE= in the service unit) and retry","Reduce socket churn / wait out TIME_WAIT, or tune the ephemeral port range (sysctl net.ipv4.ip_local_port_range)","Stop unneeded VMs/port-forwards (`colima stop`, prune docker networks) to release sockets","If sandboxed, grant network-bind access or run outside the sandbox"],"exampleFix":"# before\n$ colima start\nFATA[0000] error picking an available port: ...: too many open files\n\n# after\n$ ulimit -n 4096\n$ colima start","handlingStrategy":"retry","validationCode":"// probe socket-creation ability before the fatal path\nif l, err := net.Listen(\"tcp\", \"127.0.0.1:0\"); err != nil {\n    log.Fatalf(\"cannot bind sockets (check ulimit -n / sandbox): %v\", err)\n} else { _ = l.Close() }","typeGuard":null,"tryCatchPattern":"// util.RandomAvailablePort exits on failure; if you need resilience,\n// implement your own picker and retry with backoff:\nfor attempt := 0; attempt < 3; attempt++ {\n    if l, err := net.Listen(\"tcp\", \":0\"); err == nil {\n        port := l.Addr().(*net.TCPAddr).Port\n        _ = l.Close()\n        return port\n    }\n    time.Sleep(200 * time.Millisecond)\n}","preventionTips":["Raise LimitNOFILE / ulimit -n on hosts running many VMs or forwards","Stop unused colima profiles to release held sockets and fds","Monitor ephemeral-port and fd usage before it exhausts","Avoid running colima inside no-network sandboxes"],"tags":["network","ports","fatal","resource-exhaustion"],"backgroundTag":null,"analyzedSha":"c3a5f9184d83a197184f897a9f07eb3c01b3bc88","analyzedAt":"2026-08-15T18:58:08.334Z","schemaVersion":2},"datasetVersion":"2026-08-15T22:17:37.221Z"}