{"record":{"id":"247348441b0816c1","repo":"valyala/fasthttp","slug":"cannot-bind-to-q-w","errorCode":null,"errorMessage":"cannot bind to %q: %w","messagePattern":"cannot bind to %q: %w","errorType":"error_code","errorClass":null,"httpStatus":null,"severity":"critical","filePath":"tcplisten/tcplisten.go","lineNumber":123,"sourceCode":"\t\tif err = unix.SetsockoptInt(fd, unix.SOL_SOCKET, soReusePort, 1); err != nil {\n\t\t\treturn fmt.Errorf(\"cannot enable so_reuseport: %w\", err)\n\t\t}\n\t}\n\n\tif cfg.DeferAccept {\n\t\tif err = enableDeferAccept(fd); err != nil {\n\t\t\treturn err\n\t\t}\n\t}\n\n\tif cfg.FastOpen {\n\t\tif err = enableFastOpen(fd); err != nil {\n\t\t\treturn err\n\t\t}\n\t}\n\n\tif err = unix.Bind(fd, sa); err != nil {\n\t\treturn fmt.Errorf(\"cannot bind to %q: %w\", addr, err)\n\t}\n\n\tbacklog := cfg.Backlog\n\tif backlog <= 0 {\n\t\tif backlog, err = soMaxConn(); err != nil {\n\t\t\treturn fmt.Errorf(\"cannot determine backlog to pass to listen(2): %w\", err)\n\t\t}\n\t}\n\tif err = unix.Listen(fd, backlog); err != nil {\n\t\treturn fmt.Errorf(\"cannot listen on %q: %w\", addr, err)\n\t}\n\n\treturn nil\n}\n\nfunc getSockaddr(network, addr string) (sa unix.Sockaddr, soType int, err error) {\n\ttcpAddr, err := net.ResolveTCPAddr(network, addr)\n\tif err != nil {","sourceCodeStart":105,"sourceCodeEnd":141,"githubUrl":"https://github.com/valyala/fasthttp/blob/c96f600972c6f4a7a30d664257b340ebe9d60124/tcplisten/tcplisten.go#L105-L141","documentation":"fdSetup reached the bind step and unix.Bind(fd, sa) failed, so NewListener aborts with this error wrapping the errno. Binding is where permission problems, port conflicts, and address validity issues surface, making this the most common listener-creation failure.","triggerScenarios":"Calling NewListener with an address that is already in use (EADDRINUSE), requires privileges (EACCES for ports <1024 without CAP_NET_BIND_SERVICE), doesn't exist/assign to the host (EADDRNOTAVAIL), or the family is unavailable (EAFNOSUPPORT).","commonSituations":"Port already held by another process (including a previous instance without SO_REUSEPORT semantics); binding low ports as non-root in containers; binding to a specific IP not present on the machine; Docker port conflicts.","solutions":["Check EADDRINUSE: find and stop the conflicting process (lsof -i :8080 / ss -ltnp) or choose another port","Check EACCES: run with CAP_NET_BIND_SERVICE, use setcap 'cap_net_bind_service=+ep' on the binary, or bind to a port >=1024","Check EADDRNOTAVAIL: bind to 0.0.0.0/[::] or an IP that actually exists on the host","Use ReusePort across your own instances only; add retry/backoff for transient conflicts during deploys"],"exampleFix":"// before\nln, err := cfg.NewListener(\"tcp\", \":80\") // EACCES as non-root\n// after\nln, err := cfg.NewListener(\"tcp\", \":8080\") // or grant cap_net_bind_service:\n// sudo setcap 'cap_net_bind_service=+ep' /path/to/app","handlingStrategy":"retry","validationCode":"// preflight: is the port free and bindable?\nfunc canBind(addr string) error {\n    l, err := net.Listen(\"tcp\", addr)\n    if err != nil { return err }\n    return l.Close()\n}","typeGuard":"null","tryCatchPattern":"ln, err := cfg.NewListener(\"tcp\", addr)\nif err != nil {\n    if strings.Contains(err.Error(), \"cannot bind\") {\n        var errno syscall.Errno\n        if errors.As(err, &errno) {\n            switch errno {\n            case syscall.EADDRINUSE:\n                time.Sleep(2 * time.Second) // wait for graceful shutdown, retry\n                ln, err = cfg.NewListener(\"tcp\", addr)\n            case syscall.EACCES:\n                log.Fatal(\"need CAP_NET_BIND_SERVICE for privileged port\")\n            case syscall.EADDRNOTAVAIL:\n                log.Fatal(\"bind IP not present on this host\")\n            }\n        }\n    }\n}","preventionTips":["Check port occupancy (ss -ltnp / lsof -i) before deploy","Use unprivileged ports >=1024 or grant CAP_NET_BIND_SERVICE/setcap","Bind to 0.0.0.0/[::] unless the specific IP is guaranteed present","Coordinate restarts with SO_REUSEPORT or socket activation to avoid EADDRINUSE windows","Add bounded retry with backoff for transient bind conflicts during rolling deploys"],"tags":["network","bind","port-conflict","permissions"],"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"}