{"record":{"id":"d5d77b719101d784","repo":"valyala/fasthttp","slug":"prefork-listen-tcp-s-w","errorCode":null,"errorMessage":"prefork: listen tcp %s: %w","messagePattern":"prefork: listen tcp (.+?): %w","errorType":"exception","errorClass":null,"httpStatus":null,"severity":"error","filePath":"prefork/prefork.go","lineNumber":314,"sourceCode":"\t\tgo p.watchMaster(os.Getppid())\n\t}\n\n\treturn ln, nil\n}\n\nfunc (p *Prefork) setTCPListenerFiles(addr string) error {\n\tif p.Network == \"\" {\n\t\tp.Network = defaultNetwork\n\t}\n\n\ttcpAddr, err := net.ResolveTCPAddr(p.Network, addr)\n\tif err != nil {\n\t\treturn fmt.Errorf(\"prefork: resolve %s/%s: %w\", p.Network, addr, err)\n\t}\n\n\ttcpListener, err := net.ListenTCP(p.Network, tcpAddr)\n\tif err != nil {\n\t\treturn fmt.Errorf(\"prefork: listen tcp %s: %w\", addr, err)\n\t}\n\n\tlistenerFile, err := tcpListenerFile(tcpListener)\n\tif err != nil {\n\t\t// Close the bound listener so we don't leak the socket/fd when\n\t\t// File() fails. p.ln is intentionally only assigned after this\n\t\t// point so the caller never sees a half-initialised state.\n\t\t_ = tcpListener.Close()\n\t\treturn fmt.Errorf(\"prefork: dup listener fd: %w\", err)\n\t}\n\n\tp.ln = tcpListener\n\tp.files = []*os.File{listenerFile}\n\n\treturn nil\n}\n\n// childEnv returns os.Environ() with the prefork child marker variable set,","sourceCodeStart":296,"sourceCodeEnd":332,"githubUrl":"https://github.com/valyala/fasthttp/blob/c96f600972c6f4a7a30d664257b340ebe9d60124/prefork/prefork.go#L296-L332","documentation":"Returned by Prefork.setTCPListenerFiles when net.ListenTCP fails to bind the requested address/network. The library wraps the underlying error with the failing address so the developer knows exactly which address:port could not be bound during prefork listener setup. Prefork requires a bound listener that can be duplicated to child processes, so this failure aborts prefork startup.","triggerScenarios":"Calling prefork with an address that is already in use by another process, a privileged port (<1024) without root/CAP_NET_BIND_SERVICE, an invalid network type (e.g. tcp6 with an IPv4 address), or an unresolvable/invalid address string.","commonSituations":"Another instance of the app is still running and holding the port; running in a container without privileges binding to port 80/443; misconfigured LISTEN_ADDR environment variable; Docker port conflicts.","solutions":["Free the port: stop or reconfigure the process already bound to the address (lsof -i :port / ss -ltnp).","Use an unprivileged port or run with CAP_NET_BIND_SERVICE (setcap) if binding ports <1024.","Verify the network type matches the address family (tcp4 vs tcp6) and the address string is valid.","Check that the address resolves in the current environment (no bogus hostnames in config)."],"exampleFix":"// before\nprefork: p.Listen(\":80\") without privileges\n// after\np.Listen(\":8080\") or grant capability: sudo setcap 'cap_net_bind_service=+ep' /path/to/app","handlingStrategy":"validation","validationCode":"// Before enabling prefork, check the address is bindable:\nln, err := net.Listen(\"tcp\", addr)\nif err != nil { log.Fatalf(\"cannot bind %s: %v\", addr, err) }\nln.Close()","typeGuard":null,"tryCatchPattern":"if err := p.Listen(addr); err != nil {\n    var oe *net.OpError\n    if errors.As(err, &oe) && errors.Is(oe.Err, syscall.EADDRINUSE) {\n        log.Fatalf(\"port in use: %v\", err)\n    }\n    log.Fatalf(\"prefork listen failed: %v\", err)\n}","preventionTips":["Choose unprivileged ports unless you grant CAP_NET_BIND_SERVICE.","Add a startup pre-flight bind check in deploy scripts.","Match tcp4/tcp6 network to the configured address family.","Ensure old instances are stopped before starting (use pidfiles/systemd)."],"tags":["go","network","prefork","listen-error"],"backgroundTag":"address-already-in-use","analyzedSha":"c96f600972c6f4a7a30d664257b340ebe9d60124","analyzedAt":"2026-08-31T22:48:28.265Z","contentChangedAt":null,"schemaVersion":2},"datasetVersion":"2026-09-08T05:18:18.240Z"}