What causes "cannot bind to %q: %w" in valyala/fasthttp?

Check EADDRINUSE: find and stop the conflicting process (lsof -i :8080 / ss -ltnp) or choose another port

cannot bind to %q: %w

Error message

cannot bind to %q: %w

What it means

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.

Source

Thrown at tcplisten/tcplisten.go:123

		if err = unix.SetsockoptInt(fd, unix.SOL_SOCKET, soReusePort, 1); err != nil {
			return fmt.Errorf("cannot enable so_reuseport: %w", err)
		}
	}

	if cfg.DeferAccept {
		if err = enableDeferAccept(fd); err != nil {
			return err
		}
	}

	if cfg.FastOpen {
		if err = enableFastOpen(fd); err != nil {
			return err
		}
	}

	if err = unix.Bind(fd, sa); err != nil {
		return fmt.Errorf("cannot bind to %q: %w", addr, err)
	}

	backlog := cfg.Backlog
	if backlog <= 0 {
		if backlog, err = soMaxConn(); err != nil {
			return fmt.Errorf("cannot determine backlog to pass to listen(2): %w", err)
		}
	}
	if err = unix.Listen(fd, backlog); err != nil {
		return fmt.Errorf("cannot listen on %q: %w", addr, err)
	}

	return nil
}

func getSockaddr(network, addr string) (sa unix.Sockaddr, soType int, err error) {
	tcpAddr, err := net.ResolveTCPAddr(network, addr)
	if err != nil {

View on GitHub (pinned to c96f600972)

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

Example fix

// before
ln, err := cfg.NewListener("tcp", ":80") // EACCES as non-root
// after
ln, err := cfg.NewListener("tcp", ":8080") // or grant cap_net_bind_service:
// sudo setcap 'cap_net_bind_service=+ep' /path/to/app

Defensive patterns

Strategy: retry

Validate before calling

// preflight: is the port free and bindable?
func canBind(addr string) error {
    l, err := net.Listen("tcp", addr)
    if err != nil { return err }
    return l.Close()
}

Type guard

null

Try / catch

ln, err := cfg.NewListener("tcp", addr)
if err != nil {
    if strings.Contains(err.Error(), "cannot bind") {
        var errno syscall.Errno
        if errors.As(err, &errno) {
            switch errno {
            case syscall.EADDRINUSE:
                time.Sleep(2 * time.Second) // wait for graceful shutdown, retry
                ln, err = cfg.NewListener("tcp", addr)
            case syscall.EACCES:
                log.Fatal("need CAP_NET_BIND_SERVICE for privileged port")
            case syscall.EADDRNOTAVAIL:
                log.Fatal("bind IP not present on this host")
            }
        }
    }
}

Prevention

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

When it happens

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

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

Related errors

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