{"record":{"id":"45409c5586ed956d","repo":"lima-vm/lima","slug":"unexpected-port-d","errorCode":null,"errorMessage":"unexpected port %d","messagePattern":"unexpected port (.+?)","errorType":"exception","errorClass":null,"httpStatus":null,"severity":"error","filePath":"pkg/freeport/freeport.go","lineNumber":29,"sourceCode":"\nfunc TCP() (int, error) {\n\tlAddr0, err := net.ResolveTCPAddr(\"tcp4\", \"127.0.0.1:0\")\n\tif err != nil {\n\t\treturn 0, err\n\t}\n\tl, err := net.ListenTCP(\"tcp4\", lAddr0)\n\tif err != nil {\n\t\treturn 0, err\n\t}\n\tdefer l.Close()\n\tlAddr := l.Addr()\n\tlTCPAddr, ok := lAddr.(*net.TCPAddr)\n\tif !ok {\n\t\treturn 0, fmt.Errorf(\"expected *net.TCPAddr, got %v\", lAddr)\n\t}\n\tport := lTCPAddr.Port\n\tif port <= 0 {\n\t\treturn 0, fmt.Errorf(\"unexpected port %d\", port)\n\t}\n\treturn port, nil\n}\n\nfunc UDP() (int, error) {\n\tlAddr0, err := net.ResolveUDPAddr(\"udp4\", \"127.0.0.1:0\")\n\tif err != nil {\n\t\treturn 0, err\n\t}\n\tl, err := net.ListenUDP(\"udp4\", lAddr0)\n\tif err != nil {\n\t\treturn 0, err\n\t}\n\tdefer l.Close()\n\tlAddr := l.LocalAddr()\n\tlUDPAddr, ok := lAddr.(*net.UDPAddr)\n\tif !ok {\n\t\treturn 0, fmt.Errorf(\"expected *net.UDPAddr, got %v\", lAddr)","sourceCodeStart":11,"sourceCodeEnd":47,"githubUrl":"https://github.com/lima-vm/lima/blob/dd909d0973cd84fa35f9e1693181b4585ea616c1/pkg/freeport/freeport.go#L11-L47","documentation":"After successfully asserting the listener address is a *net.TCPAddr, TCP() verifies the kernel-assigned port is positive. A port <= 0 means the OS handed back an unusable port number, so the library refuses to return it. This is another invariant check on the kernel's port allocator.","triggerScenarios":"Calling freeport.TCP() when the OS assigns port 0 or a negative port in the *net.TCPAddr result — e.g. a kernel/container network bug or an environment where ephemeral port allocation is broken.","commonSituations":"Container/sandbox environments with broken networking, heavily constrained CI runners, or OS-level misconfiguration of the ephemeral port range.","solutions":["Retry the call; port allocation failures are often transient.","Verify the host's ephemeral port range is sane (e.g. net.ipv4.ip_local_port_range on Linux).","Check container/sandbox network configuration; restart the networking stack or the container.","If persistent, report with OS/kernel details as this indicates a port-allocation defect."],"exampleFix":null,"handlingStrategy":"retry","validationCode":null,"typeGuard":null,"tryCatchPattern":"var port int\nvar err error\nfor i := 0; i < 3; i++ {\n    port, err = freeport.TCP()\n    if err == nil { break }\n    time.Sleep(100 * time.Millisecond)\n}\nif err != nil { return fmt.Errorf(\"port allocation failed after retries: %w\", err) }","preventionTips":["Verify host ephemeral port range configuration","Avoid broken container network namespaces","Check for port-table exhaustion under load"],"tags":["network","freeport","port-allocation"],"backgroundTag":"invalid-port-assigned","analyzedSha":"dd909d0973cd84fa35f9e1693181b4585ea616c1","analyzedAt":"2026-09-01T14:24:59.842Z","contentChangedAt":null,"schemaVersion":2},"datasetVersion":"2026-09-08T10:18:20.063Z"}