Happy Eyeballs
Happy Eyeballs races IPv4 and IPv6 connection attempts with a small stagger, so a broken protocol path on one family cannot stall the user while the other succeeds immediately.
Definition
Happy Eyeballs is a client connection algorithm that resolves a hostname to addresses of multiple families and starts attempts in a staggered race: IPv6 first by policy, with IPv4 following after a short delay if no connection completes. Whichever TCP or QUIC handshake finishes first wins, bounding worst-case latency to the fast path.
Context and scope
Implemented in browsers, operating system libraries, and HTTP clients to survive dual-stack environments where one family is broken by misconfigured routers, firewalls, or DNS.
Common misconceptions
- Happy Eyeballs prefers IPv6 always — it prefers whichever completes first and biases the stagger by policy
- It speeds up every connection — it only helps when one address family is broken; otherwise it adds nothing
- It is a DNS feature — it is a connection scheduling policy applied after resolution
Anti-patterns
- Trying all addresses strictly in DNS order with no timeout, hanging for minutes on a dead IPv6 path
- Setting the inter-family delay to zero and doubling connection attempts across every lookup
- Testing only single-stack environments and shipping clients that have never exercised the race logic
Related concepts
Related examples
Authoritative source
What it is
A hostname often resolves to IPv6 and IPv4 addresses, and one family may be silently broken. Sequential attempts inherit the broken family full timeout delay. Happy Eyeballs overlaps the attempts with a small offset so the working family completes while the broken one is still retrying.
How it works
The client resolves, sorts addresses by family, opens the preferred one, and arms a timer of roughly 250 to 300 milliseconds. If it fires without success, it starts the other family in parallel. Subsequent addresses continue in a similar backoff. Success cancels pending attempts.
When to use it
Any dual-stack client that must feel fast for users on partially broken networks — which is a large fraction of consumer IPv6 deployments. Version 3 of the algorithm extends the race to include HTTPS records and QUIC attempts so protocol selection joins family selection.
Pitfalls
The stagger must be tuned: zero causes simultaneous duplicate traffic, too long reproduces the serial stall. Resolvers that only return one family disable the strategy entirely. Metrics should split connection latency by family to see which path actually serves users.