Happy Eyeballs helps an application establish a connection when a hostname offers several possible IP addresses. It gives a preferred candidate a head start, then introduces alternatives while connection setup is still pending. A slow IPv6 attempt can therefore be overtaken by IPv4 without holding up the application for an entire connection timeout.

The chosen family depends on the addresses available, their ordering, the spacing between attempts, and when a connection succeeds. An IPv6 preference influences the beginning of the race; it does not guarantee an IPv6 winner.

To understand a particular result, follow the connection timeline. The Domain Name System (DNS) supplies candidates, address policy orders them, and the connection procedure decides when to try each destination.

DNS Answers Supply the Candidates

A hostname can have A records containing IPv4 addresses and AAAA records containing IPv6 addresses. Several records of either type can contribute several destinations. The client can try these addresses to reach the requested service.

Happy Eyeballs Version 2 starts asynchronous AAAA and A queries close together. Usable AAAA answers allow an immediate connection start. If A answers arrive first, the client briefly waits for an AAAA response; the recommended resolution delay is 50 milliseconds. IPv4 attempts can begin when that wait ends or an AAAA response confirms that no records are available. Late IPv6 answers can join the candidates before a winner emerges.

That resolution delay concerns missing DNS information. A separate connection attempt delay controls the spacing between connection starts. Combining both waits into one timer obscures whether an application was waiting for an address or already trying to reach it.

Address Policy Orders the Destinations

Before racing connections, the client needs an ordered set of usable destinations. Default address selection considers usable source addresses, compatible address scopes, and the priorities and labels assigned by policy. Scope identifies where an address is usable, while policy labels help match suitable source and destination addresses. With otherwise suitable candidates, the default policy can favor IPv6.

Source address selection determines which local address the client uses to contact each destination. Destination ordering determines which remote address the client tries first. Happy Eyeballs operates on those remote connection candidates; it does not replace the rules that choose a temporary, stable, or otherwise suitable local IPv6 address.

A preferred address does not guarantee a quick connection. A correctly configured IPv6 address may still lead through a path that is currently losing packets. The ordering establishes the starting position, leaving actual connection completion to determine the outcome.

Interleave IPv6 and IPv4 Candidates

Interleaving changes the arrangement of the sorted candidates so that the second family appears near the front. The first address family count determines how many preferred-family addresses lead the list before an address from the other family appears. A count of one produces an alternating sequence when both families have enough candidates.

Consider this illustrative set of documentation addresses, already ordered within each family:

  • First IPv6 candidate: 2001:db8:90::84.
  • Second IPv6 candidate: 2001:db8:90::85.
  • First IPv4 candidate: 198.51.100.84.
  • Second IPv4 candidate: 198.51.100.85.

With IPv6 leading and a first address family count of one, the attempt order becomes 2001:db8:90::84, 198.51.100.84, 2001:db8:90::85, and 198.51.100.85. IPv4 gets an opportunity before the client has worked through both IPv6 destinations. If one family supplies more addresses, its remaining candidates still need consideration after the other family runs out.

Connection Attempts Start at Different Times

Staggering starts the next attempt after a short wait while the previous attempt can remain in progress. This preserves a head start for the preferred destination without requiring it to finish or exhaust its timeout before an alternative starts. The connection attempt delay controls how long that initial opportunity lasts.

The Version 2 baseline recommendation is 250 milliseconds. Implementations can use different settings: libcurl, a library that applications use to transfer data, defaults to 200 milliseconds for its Happy Eyeballs timeout. In libcurl, another connection attempt can start after that interval while an earlier one remains pending and may still succeed. A reported failure can allow the sequence to move on sooner.

A longer gap gives the first candidate more time without competition. A shorter gap lets an alternative challenge it earlier. Those choices change the timeline even when the address list and the connection durations remain identical.

The delay is therefore part of the selection behavior. Seeing IPv6 listed first and IPv4 chosen later is entirely compatible with a procedure that initially preferred IPv6.

The First Successful Connection Wins

For the ordinary Transmission Control Protocol (TCP) example, success means that a connection has been established through the TCP handshake, the initial message exchange that opens the connection. Receiving a DNS answer, transmitting an initial SYN connection request, or getting a reply to a separate ping does not establish that connection.

Once a connection succeeds, the application uses it and cancels the competing attempts. Addresses not yet tried are left unused for that connection. The procedure seeks a usable connection promptly; it does not wait for every candidate to finish so it can compare all their results.

This distinction matters when reading a connection log. The first destination in the list can lose, and an attempt still pending when another succeeds can be canceled without ever reporting a network failure. A canceled candidate has an incomplete result.

A Timeline Shows How Either Family Can Win

The following hypothetical cases use a 250-millisecond gap and two available candidates, with IPv6 starting first. DNS resolution is already complete, and time zero is the start of the first connection attempt. These numbers illustrate the selection logic; they are not measurements from a network.

IPv4 Finishes First after Starting Later

Assume the IPv6 attempt would need 310 milliseconds to connect if allowed to continue. At 250 milliseconds it is still pending, so the IPv4 attempt starts. IPv4 needs another 50 milliseconds and completes at time 300.

The finish times would be 310 for IPv6 and 250 plus 50, or 300, for IPv4. IPv4 wins at 300 milliseconds. The IPv6 attempt is canceled before its hypothetical completion at 310, so the client does not obtain a completed 310-millisecond IPv6 result.

IPv6 Keeps Its Head Start

Now assume IPv6 connects in 280 milliseconds. IPv4 still starts at time 250 and would require 80 milliseconds of its own, placing its hypothetical finish at 330.

IPv6 wins at 280 and the pending IPv4 attempt is canceled. Although IPv4’s assumed setup duration of 80 milliseconds is shorter than IPv6’s 280 milliseconds, its later start prevents it from winning. The selected family is therefore not necessarily the family with the shortest isolated setup duration.

This case also explains why replacing the configured gap with a different value can change a result. If IPv4 were given an earlier start, its hypothetical finish would move earlier too; the original outcome depends on the stated timing assumptions.

Only the First Attempt Needs to Start

If IPv6 connects at 190 milliseconds, selection finishes before the scheduled IPv4 start at 250. There is no IPv4 connection result to compare. Describing this as an IPv4 failure would invent an event that never occurred.

For all three cases, record the start and completion times separately. Recording only how long each attempt takes leaves out the delay before it starts, which can change the winner.

Why the Chosen Family Can Change

The next connection may receive a different address list or encounter different packet loss and server response times. Changes to destination policy can also alter which suitable address leads the list. One successful IPv6 or IPv4 connection does not guarantee the same result next time.

Recent connection history can influence candidates. Version 2 forbids using this history across different network interfaces and recommends clearing it when the device changes networks. Connection history from one network may no longer be useful after the device moves to another.

For a particular connection, compare the actual candidates, their start times, any explicit errors, and the selected remote endpoint. Distinguish an attempt that failed from one that was canceled, and distinguish both from an address that was never attempted.

What a Successful TCP Connection Tells You

An established TCP connection identifies a local and remote endpoint pair. Its ordinary data stream continues through that connection; Happy Eyeballs does not choose IPv4 for one segment and IPv6 for the next.

The TCP winner also does not prove that every later application step will succeed. Transport Layer Security (TLS) setup and certificate matching remain separate requirements for a secure service. A connection can establish successfully and then encounter a problem during those later steps.

When a report says “IPv4 selected,” retain the destination address and the stage at which selection was recorded. A TCP connection event and a completed secure application session provide different information. Keeping those events distinct makes a family-selection result useful without turning an early connection success into a claim about the entire request.