valyala/fasthttp · critical

cannot create listening unblocked socket: %w

Error message

cannot create listening unblocked socket: %w

What it means

This is the terminal error in newSocketCloexec on non-z/OS platforms: unix.Socket with SOCK_NONBLOCK|SOCK_CLOEXEC failed with an errno other than EPROTONOSUPPORT or EINVAL (which would trigger the fallback to newSocketCloexecOld). The library cannot create the listening socket at all, so NewListener fails immediately.

Source

Thrown at tcplisten/socket_other.go:21

package tcplisten

import (
	"fmt"

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

func newSocketCloexec(domain, typ, proto int) (int, error) {
	fd, err := unix.Socket(domain, typ|unix.SOCK_NONBLOCK|unix.SOCK_CLOEXEC, proto)
	if err == nil {
		return fd, nil
	}

	if err == unix.EPROTONOSUPPORT || err == unix.EINVAL {
		return newSocketCloexecOld(domain, typ, proto)
	}

	return -1, fmt.Errorf("cannot create listening unblocked socket: %w", err)
}

View on GitHub (pinned to c96f600972)

Solutions

1. Inspect the wrapped errno: EMFILE/ENFILE means raise RLIMIT_NOFILE or reduce fd usage
2. EPERM/operation-not-permitted in containers: adjust seccomp profile to allow socket2 with SOCK_NONBLOCK/SOCK_CLOEXEC
3. Verify the network string ("tcp", "tcp4", "tcp6") matches an available address family
4. Run on an updated kernel/Go version so the modern socket() path or fallback succeeds

Example fix

// before
ln, err := cfg.NewListener("tcp6", ":8080") // EAFNOSUPPORT if IPv6 disabled
// after
if hasIPv6() { // e.g. check /proc/sys/net/ipv6 or dial test
    ln, err = cfg.NewListener("tcp6", ":8080")
} else {
    ln, err = cfg.NewListener("tcp4", ":8080")
}

// precondition checks before NewListener
fds, _ := syscall.Getrlimit(syscall.RLIMIT_NOFILE)
if fds.Cur < 1024 { /* raise limit or reduce usage */ }
if _, err := net.Dial("tcp", "127.0.0.1:1"); err != nil {
    if errno, ok := err.(*net.OpError); ok && strings.Contains(errno.Err.Error(), "socket") {
        log.Fatal("socket() blocked by sandbox")
    }
}

null

ln, err := cfg.NewListener(network, addr)
if err != nil {
    if strings.Contains(err.Error(), "cannot create listening unblocked socket") {
        var errno syscall.Errno
        if errors.As(err, &errno) && (errno == syscall.EMFILE || errno == syscall.ENFILE) {
            time.Sleep(backoff) // transient fd exhaustion: retry
            ln, err = cfg.NewListener(network, addr)
        }
    }
}

When it happens

Trigger: Any NewListener call where socket(domain, typ|SOCK_NONBLOCK|SOCK_CLOEXEC, proto) returns e.g. EPERM, EMFILE, ENFILE, EACCES, EAFNOSUPPORT, or EPROTOTYPE.

Common situations: File descriptor exhaustion under load (EMFILE/ENFILE); seccomp profiles (Docker/gVisor) blocking socket() flags with EPERM; wrong network family requested; restricted environments where the modern flags are rejected outright.

Related errors

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

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