You click a link. Your computer finds the website’s address. Everything should be ready.
Except the website has several addresses—and the first one your computer tries leads to a connection that never quite happens.
A strictly patient application might wait for that attempt to time out before trying another address. You experience an unexplained pause, even though a working alternative was available all along.
Happy Eyeballs is a connection-establishment strategy designed to avoid that unnecessary wait. It coordinates attempts to reach a service through different addresses, giving alternatives a chance before the first attempt has exhausted your patience.
The memorable name belongs to a practical idea: keep the person looking at the screen happy.
Why One Website Can Have Several Addresses
A hostname does not necessarily identify one IP address.
A DNS lookup can return:
- A records, containing IPv4 addresses.
- AAAA records, containing IPv6 addresses.
- Multiple addresses within either family.
A device supporting both IPv4 and IPv6 is commonly described as dual stack. When the destination also supports both, the client may have several possible ways to connect.
That sounds like an advantage. Sometimes, however, one option behaves badly.
An IPv6 route might be broken. A firewall might silently discard connection attempts. A particular destination address might be unreachable while another works.
DNS can provide an address without proving that a connection to it will succeed from your device, on your current network, at this moment.
The Problem with Waiting Politely
Consider an application that works through its address list sequentially:
- Try the first address.
- Wait until it succeeds or fails.
- Only then try the next address.
This approach is easy to understand. Its weakness appears when failure is slow.
A prompt rejection can be handled quickly. Silence is harder: the client must allow time for a response that might simply be delayed.
The original Happy Eyeballs specification, published as RFC 6555 in 2012, addressed the particularly frustrating case where IPv4 worked but IPv6 did not. Supporting both protocols should not make an application feel slower than one supporting only IPv4.
The solution was to give the working alternative an earlier opportunity.
How Happy Eyeballs Works
Happy Eyeballs Version 2, described in RFC 8305, coordinates several stages:
- Resolve the hostname, obtaining possible destination addresses.
- Order the candidates according to address-selection policy.
- Start a connection attempt.
- Start another suitable attempt after a short delay if a connection has not yet been established.
- Select a successful connection and cancel unnecessary outstanding attempts.
The attempts can overlap. A client therefore does not need to wait for one address to reach its full connection timeout before exploring another.
This is a staggered race, rather than an instruction to contact every address simultaneously.
DNS response timing matters too. A well-designed implementation coordinates resolution and connection establishment so that waiting for one address family does not unnecessarily block useful progress with another.
A Race You Never See
Imagine the following simplified example:
| Time | What happens |
|---|---|
| 0 ms | The client begins connecting to an IPv6 address. |
| 250 ms | With no successful connection yet, it starts an IPv4 attempt. |
| 310 ms | The IPv4 connection succeeds. |
| Shortly afterward | The unused IPv6 attempt is cancelled. |
These figures illustrate the mechanism; they are not measurements from a real connection or universal settings.
The useful outcome is that the client connects after roughly 310 milliseconds instead of waiting for the unsuccessful attempt’s full timeout.
The head start also matters. If the initial IPv6 attempt had succeeded promptly, the alternative attempt might never have been needed.
A useful analogy is opening a second checkout when the first queue stops moving. You preserve the first opportunity without allowing it to block every other possibility.
Does IPv4 Always Compete Against IPv6?
IPv4 and IPv6 provide the most familiar example, but the underlying problem is broader: a service can have multiple candidate addresses with different connectivity characteristics.
Happy Eyeballs is therefore more useful than a simple rule saying “try IPv6, then fall back to IPv4.”
It combines address selection, timing, and overlapping attempts.
Nor does the winning connection establish that one protocol is universally faster. It shows that a particular attempt became usable first under the conditions of that connection.
Move the same device to another network, change the destination, or try again later, and the outcome may differ.
Faster Connection Setup Is Not Faster Downloading
Happy Eyeballs primarily reduces avoidable delay while establishing a connection.
Once that connection is carrying traffic, other mechanisms determine performance: available bandwidth, round-trip time, congestion control, packet loss, and application behavior.
A connection that succeeds first is not necessarily the one that would sustain the highest throughput during a large transfer.
Similarly, completing a TCP handshake does not prove that every later step will work. TLS negotiation can fail, the application can return an error, or larger packets can encounter a path-MTU problem.
The finishing line depends on the implementation and the connection stack involved. Happy Eyeballs addresses connection selection; it does not certify the complete health of a service.
See the Two Address Families Separately with curl
When investigating a connection problem, it can help to compare IPv4 and IPv6 explicitly.
For a destination you know publishes both address types, curl provides these options:
curl -4 -I --connect-timeout 5 --max-time 10 https://example.com/
curl -6 -I --connect-timeout 5 --max-time 10 https://example.com/Here:
-4restricts the attempt to IPv4.-6restricts it to IPv6.-Irequests HTTP response headers.- The timeout options bound the connection attempt and overall operation.
On Windows, use curl.exe if your shell maps curl to another command.
These forced-family tests do not demonstrate Happy Eyeballs itself: each removes the alternative family from consideration. They help investigate the conditions that make address-family selection important.
A failed IPv6 test alone does not identify the cause. Check the destination’s DNS records, local connectivity, routing, firewalls, and any proxy involved. A single result is a clue, not a diagnosis.
curl also exposes a Happy Eyeballs timing option, but implementations and defaults vary. Changing a delay without understanding the underlying problem can simply change how that problem appears.
Why Application Developers Should Care
A network-capable operating system does not automatically make every application’s connection logic robust.
An application can still resolve a hostname, take the first address returned, and wait excessively before considering another.
Apple’s networking guidance recommends using suitable connect-by-name APIs, which accept a hostname and manage connection details. Its preferred networking APIs incorporate Happy Eyeballs behavior alongside other platform networking features.
For developers, the lesson is to understand what the chosen library already provides. A mature connection stack can handle complexities that are easy to overlook in a short socket example.
Avoid treating a cached successful address as permanently correct, and distinguish racing connection attempts from repeating application operations. Establishing an alternative connection is a different decision from submitting the same transaction twice.
A Safety Net Can Hide a Broken Path
Happy Eyeballs can make browsing appear healthy while one available connection path remains faulty.
The user sees a page load successfully. The network administrator may still have an IPv6 routing or filtering problem to investigate.
Disabling IPv6 permanently can conceal the symptom while leaving the underlying issue unexplained. Testing each family separately provides more useful evidence.
The broader lesson reaches beyond IPv4 and IPv6: when several viable alternatives exist, making them wait through a long sequence of failures can waste the user’s time.
Happy Eyeballs turns that observation into connection logic. Most people never notice the race—which is exactly what a successful implementation achieves.
References and Further Reading
- RFC 8305: Happy Eyeballs Version 2—Better Connectivity Using Concurrency
- RFC 6555: Happy Eyeballs—Success with Dual-Stack Hosts, the original specification, subsequently superseded by RFC 8305.
- Apple Technical Note TN3151: Choosing the Right Networking API
- curl documentation, including IPv4/IPv6 selection and Happy Eyeballs timeout options.
