HTTP/3 Support in HTTP Client API in Java 26

1. Overview

Modern applications demand faster, more reliable, and more secure network communication, and HTTP/3 addresses these requirements.

Java introduced the modern HttpClient API in Java 11 to replace the legacy HttpURLConnection API and provide built-in support for HTTP/2, asynchronous communication, and WebSocket integration. With Java 26, the HttpClient API continues its evolution by adding support for HTTP/3.

In this tutorial, we’ll explore how Java 26 extends the HttpClient API with HTTP/3 support and use it to build a Java application.

2. What Is HTTP/3?

As the name suggests, HTTP version 3, or simply HTTP/3, is the newer version of the Hypertext Transfer Protocol.

HTTP/3 delivers significant improvements in performance, reliability, and security by replacing TCP with Quick UDP Internet Connections (QUIC) as its transport layer. QUIC combines the transport and TLS 1.3 handshake into a single round trip, which cuts connection setup time compared to TCP. It’s particularly effective on high-latency and mobile networks.

QUIC streams are independent, so a lost packet affects only that stream, whereas other streams continue without interruption. Most modern browsers now support HTTP/3 and use it automatically when a server advertises it.

3. Using HTTP/3 in Java 26

We can continue using the same high-level HTTP Client API while the runtime handles protocol negotiation internally.

3.1. Declaring HTTP/3

Before we send an HTTP request, we first create an instance of an HttpClient. HttpClient instances can be configured and created via their builder:

public Http3Demo() {
    this.client = HttpClient.newBuilder()
      .version(HttpClient.Version.HTTP_3)
      .build();
}

When we call .version(HttpClient.Version.HTTP_3), we instruct the client to prefer HTTP/3 for outgoing requests. By default, Java 26 uses HTTP/2, so existing applications require no change if we don’t need HTTP/3.

3.2. Protocol Discovery

If we set the client to use HTTP/3, the client needs to discover whether the server supports it. As HTTP/3 runs over QUIC, a UDP-based transport, whereas HTTP/1.1 and HTTP/2 run over TCP, the client can’t upgrade an existing connection to HTTP/3 the way it switches between the older versions.

We choose how the client discovers HTTP/3 per request by setting HttpOption.H3_DISCOVERY. Three modes are supported:

• ANY (default): The client uses its own algorithm to establish a connection. It may attempt HTTP/3 over QUIC and HTTP over TLS/TCP, using whichever succeeds first.
• HTTP_3_URI_ONLY: The client attempts HTTP/3 directly at the host and port from the request URI without using Alternative Services. This succeeds only if the server is already listening for HTTP/3 on that port.
• ALT_SVC: The client relies only on HTTP Alternative Services to discover HTTP/3. Servers advertise HTTP/3 through HTTP Alternative Services, defined in RFC 7838. A server can answer the first request over HTTP/1.1 or HTTP/2 and include an Alt-Svc header frame that names an h3 endpoint. The header tells the client that the same resource is available at a given host and port over HTTP/3. Then, the client can send later requests over HTTP/3. Alternatively, the server can also advertise HTTP/3 via an HTTP/2 ALTSVC frame.

If we don’t set H3_DISCOVERY, the client uses ANY by default. This option only works when HTTP/3 is the preferred version (set on the client or the request).

3.3. Sending Requests

Let’s see this in action. Our fetch() method builds and sends an HttpRequest:

public HttpResponse<String> fetch(String url) throws IOException, InterruptedException {
    HttpRequest request = HttpRequest.newBuilder(URI.create(url))
      .GET()
      .setOption(HttpOption.H3_DISCOVERY, HttpOption.Http3DiscoveryMode.HTTP_3_URI_ONLY)
      .build();
    return this.client.send(request, BodyHandlers.ofString());
}

Here, we set the discovery mode using setOption(). We use HTTP_3_URI_ONLY to attempt HTTP/3 directly at the server’s host and port, without waiting for the server to advertise it via Alt-Svc.

Note that HttpOption.H3_DISCOVERY takes effect in our example because we set HTTP/3 as the client’s preferred version. If neither the client nor the request preferred HTTP/3, the client would ignore H3_DISCOVERY.

BodyHandlers.ofString() instructs the client to read the response body as a string. The client decodes the response using the charset specified in the Content-Type header, falling back to UTF-8 if no valid charset is provided.

We continue to handle the same checked exceptions we handled with HttpClient: IOException for network or protocol failures, and InterruptedException (because the send() method blocks the calling thread).

4. Protocol Selection and Error Handling

Setting HTTP/3 preference doesn’t guarantee the client will use it. Let’s discuss how the client picks a protocol version and how it informs us it can’t use HTTP/3.

4.1. How the Client Chooses the Protocol Version

As with HTTP/2, several factors decide the actual protocol version for each request.

HTTP/3 stays off by default. We turn it on by setting the preferred version to HTTP/3 when building the client or an individual request. Once HTTP/3 is enabled, the discovery mode guides how the client establishes the exchange. If we don’t set the mode, the client uses the default mode.

However, there are exceptions that can override our preference:

• The client never sends a request over HTTP/3 unless the URI uses the https scheme.
• It also skips HTTP/3 when a proxy is used.

4.2. Handling UnsupportedProtocolVersionException

Sometimes, a client doesn’t support HTTP/3. Such a client may throw an UnsupportedProtocolVersionException:

• when building the client with HTTP/3 as its preferred version
• when sending a request that enables HTTP/3 but has the discovery mode set to HTTP_3_URI_ONLY

Since our example uses HTTP_3_URI_ONLY, production code should account for this exception around the send() call, alongside the IOException and InterruptedException we already handle.

5. Verifying HTTP/3 Support With Unit Tests

Let’s verify that our HTTP/3 client handles both supported and unsupported scenarios.

5.1. Verifying a Valid HTTP/3 Endpoint

Let’s send a request to https://cloudflare-quic.com/, a public endpoint that Cloudflare provides for HTTP/3 experiments:

@Test
void givenValidHttpsUrl_whenFetch_thenReturnsResponseBody() {
    HttpResponse<String> response;
    try {
        response = new Http3Demo().fetch(HTTP3_URL);
    } catch (IOException | InterruptedException e) {
        Assumptions.abort("Skipping: cloudflare-quic.com unreachable in this environment - " + e.getMessage());
        return;
    }
    assertEquals(200, response.statusCode());
    assertEquals(HttpClient.Version.HTTP_3, response.version());
}

We call the endpoint with Http3Demo.fetch() and expect a successful 200 OK response. Then, we use response.version() to verify whether the client successfully negotiated HTTP/3.

5.2. Rejecting a Plain HTTP Endpoint

In this test, we start a local server using plain HTTP and attempt to fetch it through our HTTP/3 client. We expect the request to throw an UnsupportedProtocolVersionException:

@Test
void givenPlainHttpUrl_whenFetch_thenThrowsUnsupportedProtocolVersionException() {
    assertThrows(UnsupportedProtocolVersionException.class,() -> new Http3Demo().fetch(
      plainBaseUrl + "/hello"));
}

This happens because HTTP/3 requires a secure HTTPS connection and uses QUIC as its transport protocol, while our local server only supports HTTP.

6. Conclusion

In this article, we learned about HTTP/3 support in Java 26’s HttpClient, which we enable by setting the version to HTTP/3 on the builder.

The rest of the HttpClient API stays the same. HTTP/2 remains the default, so our existing code continues to work without modifications. When the server doesn’t support HTTP/3, the client can use HTTP/2 or HTTP/1.1 instead in some cases.

The API also supports multiple discovery modes for more control over protocol selection.

As always, the code used in this article is available over on GitHub.