valyala/fasthttp · error

unexpected convert socket fd int to uintptr: %w

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.

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)

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 make non-blocked listening socket: %w
• cannot create listening unblocked socket: %w
• cannot create listening socket: %w
• cannot mark listening socket close-on-exec: %w
• cannot mark listening socket nonblocking: %w

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