valyala/fasthttp · critical

cannot create listening socket: %w

Error message

cannot create listening socket: %w

What it means

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.

Source

Thrown at tcplisten/socket_zos_s390x.go:14

//go:build zos && s390x

package tcplisten

import (
	"fmt"

	"golang.org/x/sys/unix"
)

func newSocketCloexec(domain, typ, proto int) (int, error) {
	fd, err := unix.Socket(domain, typ, proto)
	if err != nil {
		return -1, fmt.Errorf("cannot create listening socket: %w", err)
	}
	_, err = unix.FcntlInt(uintptr(fd), unix.F_SETFD, unix.FD_CLOEXEC)
	if err != nil {
		unix.Close(fd) //nolint:errcheck
		return -1, fmt.Errorf("cannot mark listening socket close-on-exec: %w", err)
	}
	_, err = unix.FcntlInt(uintptr(fd), unix.F_SETFL, unix.O_NONBLOCK)
	if err != nil {
		unix.Close(fd) //nolint:errcheck
		return -1, fmt.Errorf("cannot mark listening socket nonblocking: %w", err)
	}
	return fd, nil
}

View on GitHub (pinned to c96f600972)

Solutions

1. Read the wrapped errno to determine the exact cause
2. Increase the z/OS USS file descriptor limit (ulimit -n / BPXPRMxx MAXFILEPROC)
3. Confirm the requested address family (INET/INET6) is enabled on the z/OS TCP/IP stack
4. Verify the application has sufficient OMVS security permissions to open sockets

Example fix

// before
ln, err := cfg.NewListener("tcp", ":8080") // may fail on z/OS
// after
ln, err := cfg.NewListener("tcp", ":8080")
if err != nil && strings.Contains(err.Error(), "cannot create listening socket") {
    // check errno: EMFILE -> raise MAXFILEPROC, retry
}

// z/OS preflight before NewListener
if runtime.GOOS == "zos" {
    var lim syscall.Rlimit
    if err := syscall.Getrlimit(syscall.RLIMIT_NOFILE, &lim); err != nil || lim.Cur < 256 {
        return errors.New("raise MAXFILEPROC / ulimit -n before starting listener")
    }
}

null

ln, err := cfg.NewListener("tcp", addr)
if err != nil {
    if strings.Contains(err.Error(), "cannot create listening socket") {
        var errno syscall.Errno
        if errors.As(err, &errno) {
            log.Printf("socket() failed on z/OS: %v — check fd limits and TCP/IP stack config", errno)
        }
        return err
    }
}

When it happens

Trigger: 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.

Common situations: 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.

Related errors

• cannot mark listening socket close-on-exec: %w
• cannot mark listening socket nonblocking: %w
• cannot make non-blocked listening socket: %w
• cannot create listening unblocked socket: %w
• value is negative, cannot convert to uintptr

AI-assisted analysis of valyala/fasthttp@c96f600972 (2026-08-31). Data as JSON: /api/errors/35a166ff0371c713. Report an issue: GitHub.