{"record":{"id":"4a1c42232daa1e63","repo":"valyala/fasthttp","slug":"cannot-determine-backlog-to-pass-to-listen-2-w","errorCode":null,"errorMessage":"cannot determine backlog to pass to listen(2): %w","messagePattern":"cannot determine backlog to pass to listen\\(2\\): %w","errorType":"error_code","errorClass":null,"httpStatus":null,"severity":"error","filePath":"tcplisten/tcplisten.go","lineNumber":129,"sourceCode":"\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 {\n\t\treturn nil, -1, err\n\t}\n\n\tswitch network {\n\tcase \"tcp4\":\n\t\tvar sa4 unix.SockaddrInet4","sourceCodeStart":111,"sourceCodeEnd":147,"githubUrl":"https://github.com/valyala/fasthttp/blob/c96f600972c6f4a7a30d664257b340ebe9d60124/tcplisten/tcplisten.go#L111-L147","documentation":"tcplisten wraps the raw listen(2) syscall to create reusable, deferred-accept TCP listeners. When cfg.Backlog is not set (<=0), fdSetup reads the kernel's somaxconn value to derive a backlog; if that lookup fails, it cannot call listen(2) and returns this error wrapping the cause. It surfaces from NewListener.","triggerScenarios":"Calling tcplisten.NewListener with a Config whose Backlog is 0 or negative on Linux when soMaxConn() fails — i.e. /proc/sys/net/core/somaxconn exists but cannot be read due to permissions/other I/O error (a missing file is tolerated and falls back to unix.SOMAXCONN).","commonSituations":"Hardened containers/seccomp profiles blocking reads from /proc; pseudo-filesystems where /proc/sys is read-restricted or returns other I/O errors; unusual environments (some CI sandboxes) where the procfs file is present but unreadable.","solutions":["Set an explicit Backlog (>0) in the tcplisten.Config so soMaxConn() is never called","Check /proc/sys/net/core/somaxconn is readable by the process user (cat it manually)","Relax container/seccomp or AppArmor restrictions on /proc/sys reads","Check the wrapped %w error for the underlying read failure"],"exampleFix":"// before\ncfg := tcplisten.Config{ReusePort: true} // Backlog unset -> procfs lookup\nln, err := tcplisten.NewListener(cfg, \"tcp\", \":8080\")\n// after\ncfg := tcplisten.Config{ReusePort: true, Backlog: 1024} // explicit backlog skips somaxconn lookup\nln, err := tcplisten.NewListener(cfg, \"tcp\", \":8080\")","handlingStrategy":"validation","validationCode":"func backlogConfigured(cfg tcplisten.Config) bool { return cfg.Backlog > 0 }\nif !backlogConfigured(cfg) {\n    if b, err := ioutil.ReadFile(\"/proc/sys/net/core/somaxconn\"); err != nil && !os.IsNotExist(err) {\n        cfg.Backlog = 1024 // avoid procfs-dependent lookup\n    }\n}","typeGuard":null,"tryCatchPattern":"ln, err := tcplisten.NewListener(cfg, network, addr)\nif err != nil {\n    var sysErr *fs.PathError\n    if errors.As(err, &sysErr) || strings.Contains(err.Error(), \"somaxconn\") {\n        cfg.Backlog = 1024\n        ln, err = tcplisten.NewListener(cfg, network, addr)\n    }\n}","preventionTips":["Always set an explicit Backlog in production configs","Smoke-test listeners in the same container/seccomp profile as production","Never assume /proc/sys is readable in hardened environments"],"tags":["network","linux","tcp","backlog"],"backgroundTag":"somaxconn-backlog-unavailable","analyzedSha":"c96f600972c6f4a7a30d664257b340ebe9d60124","analyzedAt":"2026-08-31T22:48:28.265Z","contentChangedAt":null,"schemaVersion":2},"datasetVersion":"2026-09-08T05:18:18.240Z"}