What causes "value exceeds uint32 max value" in valyala/fasthttp?

Validate the source of the index; it should come from net.Interfaces()/InterfaceByIndex, never parsed ad hoc

value exceeds uint32 max value

Error message

value exceeds uint32 max value

What it means

safeIntToUint32 also rejects values above math.MaxUint32 that would overflow a uint32. On 64-bit platforms an int can hold larger values, so the explicit check prevents truncation when the value is embedded in a 32-bit sockaddr field.

Source

Thrown at tcplisten/tcplisten.go:195

			}
			sa6.ZoneId, err = safeIntToUint32(ifi.Index)
			if err != nil {
				return nil, -1, fmt.Errorf("unexpected convert net interface index int to uint32: %w", err)
			}
		}
		return &sa6, unix.AF_INET6, nil
	default:
		return nil, -1, errors.New("only tcp, tcp4, or tcp6 is supported " + network)
	}
}

func safeIntToUint32(i int) (uint32, error) {
	if i < 0 {
		return 0, errors.New("value is negative, cannot convert to uint32")
	}
	ui := uint64(i)
	if ui > math.MaxUint32 {
		return 0, errors.New("value exceeds uint32 max value")
	}
	return uint32(ui), nil
}

func safeIntToUintptr(i int) (uintptr, error) {
	if i < 0 {
		return 0, errors.New("value is negative, cannot convert to uintptr")
	}
	return uintptr(i), nil
}

View on GitHub (pinned to c96f600972)

Solutions

Validate the source of the index; it should come from net.Interfaces()/InterfaceByIndex, never parsed ad hoc
Range-check the value (0 <= v <= math.MaxUint32) before calling NewListener
Fix any byte-order/parsing bug producing the oversized value

Example fix

// before
idx := int(rawUint64) // may exceed uint32
// after
if rawUint64 > math.MaxUint32 { return errors.New("interface index out of range") }
idx := int(rawUint64)

Defensive patterns

Strategy: validation

Validate before calling

func validateIfaceIndexRange(idx int) error {
  if idx < 0 || uint64(idx) > math.MaxUint32 {
    return fmt.Errorf("interface index %d out of uint32 range", idx)
  }
  return nil
}

Type guard

func isUint32Safe(i int) bool { return i >= 0 && uint64(i) <= math.MaxUint32 }

Try / catch

ln, err := ctl.NewListener(network, addr)
if err != nil {
  if strings.Contains(err.Error(), "value exceeds uint32 max value") {
    return fmt.Errorf("interface index %d overflows uint32: %w", ifaceIdx, err)
  }
  return err
}

Prevention

Obtain indices only from net.Interfaces() rather than parsing raw bytes
Range-check any 64-bit parsed value before narrowing to int/uint32
Fuzz or unit-test config parsers for out-of-range numerics
Beware byte-order mistakes when reading indices from binary formats

When it happens

Trigger: getSockaddr receives an interface index (or other int parameter) exceeding 4294967295 and calls safeIntToUint32 while constructing the sockaddr for NewListener. Practically only possible on 64-bit systems with a corrupted/garbage index value.

Common situations: Garbage or byte-swapped value parsed from config or a packet read as interface index; unchecked cast of an unsigned 64-bit field into int before passing in.

Related errors

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