{"record":{"id":"35a166ff0371c713","repo":"valyala/fasthttp","slug":"cannot-create-listening-socket-w-35a166","errorCode":null,"errorMessage":"cannot create listening socket: %w","messagePattern":"cannot create listening socket: %w","errorType":"error_code","errorClass":null,"httpStatus":null,"severity":"critical","filePath":"tcplisten/socket_zos_s390x.go","lineNumber":14,"sourceCode":"//go:build zos && s390x\n\npackage tcplisten\n\nimport (\n\t\"fmt\"\n\n\t\"golang.org/x/sys/unix\"\n)\n\nfunc newSocketCloexec(domain, typ, proto int) (int, error) {\n\tfd, err := unix.Socket(domain, typ, proto)\n\tif err != nil {\n\t\treturn -1, fmt.Errorf(\"cannot create listening socket: %w\", err)\n\t}\n\t_, err = unix.FcntlInt(uintptr(fd), unix.F_SETFD, unix.FD_CLOEXEC)\n\tif err != nil {\n\t\tunix.Close(fd) //nolint:errcheck\n\t\treturn -1, fmt.Errorf(\"cannot mark listening socket close-on-exec: %w\", err)\n\t}\n\t_, err = unix.FcntlInt(uintptr(fd), unix.F_SETFL, unix.O_NONBLOCK)\n\tif err != nil {\n\t\tunix.Close(fd) //nolint:errcheck\n\t\treturn -1, fmt.Errorf(\"cannot mark listening socket nonblocking: %w\", err)\n\t}\n\treturn fd, nil\n}\n","sourceCodeStart":1,"sourceCodeEnd":28,"githubUrl":"https://github.com/valyala/fasthttp/blob/c96f600972c6f4a7a30d664257b340ebe9d60124/tcplisten/socket_zos_s390x.go#L1-L28","documentation":"On z/OS on s390x, newSocketCloexec calls unix.Socket and if it fails, the fd could not be created at all and this error is returned with the wrapped errno. This is the first step of the platform-specific socket setup (socket -> FD_CLOEXEC -> O_NONBLOCK), so every listener creation on that platform goes through it.","triggerScenarios":"Calling NewListener on z/OS s390x builds where unix.Socket(domain, typ, proto) returns an error: EMFILE/ENFILE (fd limits), EACCES, EAFNOSUPPORT, EPROTONOSUPPORT, or EPERM.","commonSituations":"z/OS USS environments with tight file descriptor quotas; address families not configured on the mainframe (IPv6 disabled); TCP stack not authorized for the requested protocol.","solutions":["Read the wrapped errno to determine the exact cause","Increase the z/OS USS file descriptor limit (ulimit -n / BPXPRMxx MAXFILEPROC)","Confirm the requested address family (INET/INET6) is enabled on the z/OS TCP/IP stack","Verify the application has sufficient OMVS security permissions to open sockets"],"exampleFix":"// before\nln, err := cfg.NewListener(\"tcp\", \":8080\") // may fail on z/OS\n// after\nln, err := cfg.NewListener(\"tcp\", \":8080\")\nif err != nil && strings.Contains(err.Error(), \"cannot create listening socket\") {\n    // check errno: EMFILE -> raise MAXFILEPROC, retry\n}","handlingStrategy":"validation","validationCode":"// z/OS preflight before NewListener\nif runtime.GOOS == \"zos\" {\n    var lim syscall.Rlimit\n    if err := syscall.Getrlimit(syscall.RLIMIT_NOFILE, &lim); err != nil || lim.Cur < 256 {\n        return errors.New(\"raise MAXFILEPROC / ulimit -n before starting listener\")\n    }\n}","typeGuard":"null","tryCatchPattern":"ln, err := cfg.NewListener(\"tcp\", addr)\nif err != nil {\n    if strings.Contains(err.Error(), \"cannot create listening socket\") {\n        var errno syscall.Errno\n        if errors.As(err, &errno) {\n            log.Printf(\"socket() failed on z/OS: %v — check fd limits and TCP/IP stack config\", errno)\n        }\n        return err\n    }\n}","preventionTips":["Verify MAXFILEPROC and per-process ulimit -n on z/OS USS before deployment","Confirm INET/INET6 address families are enabled on the TCP/IP stack","Ensure the runtime user has OMVS socket permissions","Smoke-test listener startup in the target LPAR environment early"],"tags":["network","sockets","zos","s390x","syscall"],"backgroundTag":"socket-creation-failed","analyzedSha":"c96f600972c6f4a7a30d664257b340ebe9d60124","analyzedAt":"2026-08-31T22:48:28.265Z","contentChangedAt":null,"schemaVersion":2},"datasetVersion":"2026-09-08T05:18:18.240Z"}