valyala/fasthttp · error

unexpected convert socket fd int to uintptr

Error message

unexpected convert socket fd int to uintptr: %w

What it means

NewListener created a valid socket fd, but the internal safeIntToUintptr(fd) conversion of the descriptor to uintptr failed (the helper rejects values outside the safe non-negative uintptr range). The fd is closed and NewListener returns this error before wrapping it in an *os.File for net.FileListener. In practice this almost always means the fd value was invalid (negative) rather than a genuine overflow.

Solutions

1. Check that fd limits are sane and the process is not racing with fd closure
2. Verify you are calling NewListener directly (not passing pre-opened fds) so the library controls fd creation
3. Report upstream if reproducible — this indicates an internal invariant violation
4. Update the library version; the safe-conversion helper has been revised across releases

null

null

ln, err := cfg.NewListener(network, addr)
if err != nil {
    if strings.Contains(err.Error(), "convert socket fd int to uintptr") {
        log.Printf("internal fd conversion failure; falling back to net.Listen")
        ln, err = net.Listen(network, addr) // degrade gracefully
    }
}

When it happens

Trigger: Any NewListener call where the fd returned by socket creation is negative or otherwise fails the safeIntToUintptr check — i.e. an fd leaked through as negative or an internal invariant violation.

Common situations: Corrupted error handling paths where socket creation returned -1 without an error; extreme fd counts theoretically exceeding platform uintptr width on 32-bit systems; custom forks of the library altering fd acquisition.

Related errors

• cannot create listening socket
• cannot create listening unblocked socket
• cannot enable so_reuseaddr
• cannot enable so_reuseport
• cannot make non-blocked listening socket

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

Appendix: source

Thrown at tcplisten/tcplisten.go:72

	sa, soType, err := getSockaddr(network, addr)
	if err != nil {
		return nil, err
	}

	fd, err := newSocketCloexec(soType, unix.SOCK_STREAM, unix.IPPROTO_TCP)
	if err != nil {
		return nil, err
	}

	if err = cfg.fdSetup(fd, sa, addr); err != nil {
		unix.Close(fd)
		return nil, err
	}

	fdUintptr, err := safeIntToUintptr(fd)
	if err != nil {
		unix.Close(fd)
		return nil, fmt.Errorf("unexpected convert socket fd int to uintptr: %w", err)
	}

	name := fmt.Sprintf("reuseport.%d.%s.%s", os.Getpid(), network, addr)
	file := os.NewFile(fdUintptr, name)
	ln, err := net.FileListener(file)
	if err != nil {
		file.Close()
		return nil, err
	}

	if err = file.Close(); err != nil {
		ln.Close()
		return nil, err
	}

	return ln, nil
}

View on GitHub (pinned to c96f600972)