skip to content

What does HTTP/3 change in Java's java.net.http client since JDK 26, and how do you ask for it?

level: middleimportance: nice to knowfreq 24%

answer

  1. opt-in, the default did not move
  2. QUIC, so no upgrade from TCP
  3. client preference versus request preference
  4. a discovery hint on the request
  5. read the version off the response

basics

~20 s

JDK 26 adds HTTP/3 over QUIC to java.net.http, but it stays opt-in: HTTP/2 remains the default. Set HttpClient.Version.HTTP_3 on the client or the request; sending code is unchanged, and the client still falls back unless told not to.

solid answer

~40 s

JDK 26 (JEP 517) lets `java.net.http` speak HTTP/3, which runs over QUIC on UDP with TLS 1.3 instead of TCP, but the default preference stays HTTP/2. You opt in with `.version(HttpClient.Version.HTTP_3)` on the client builder or on one `HttpRequest`, and the rest of your code does not change. No client can know in advance whether a server supports it, so discovery matters: a request-level preference tries HTTP/3 first and then falls back, while a client-level preference races HTTP/3 against TCP. The `HttpOption.H3_DISCOVERY` hint narrows that with `ALT_SVC` or `HTTP_3_URI_ONLY`, and the latter fails rather than falls back. Read `response.version()`, because a preference is not a guarantee: non-`https` requests never use HTTP/3, and the JDK's implementation does not use it through a proxy.

code

java · 35 lines
java
import java.io.IOException;
import java.net.URI;
import java.net.http.HttpClient;
import java.net.http.HttpOption;
import java.net.http.HttpOption.Http3DiscoveryMode;
import java.net.http.HttpRequest;
import java.net.http.HttpResponse;
import java.time.Duration;

public class Http3Request {
    public static void main(String[] args) throws IOException, InterruptedException {
        URI uri = URI.create(args[0]);
        HttpClient client = HttpClient.newHttpClient();

        HttpRequest preferred = HttpRequest.newBuilder(uri)
                .version(HttpClient.Version.HTTP_3)
                .timeout(Duration.ofSeconds(10))
                .build();
        HttpResponse<Void> answer =
                client.send(preferred, HttpResponse.BodyHandlers.discarding());
        System.out.println("preferred: " + answer.version());

        HttpRequest strict = HttpRequest.newBuilder(uri)
                .version(HttpClient.Version.HTTP_3)
                .setOption(HttpOption.H3_DISCOVERY, Http3DiscoveryMode.HTTP_3_URI_ONLY)
                .timeout(Duration.ofSeconds(10))
                .build();
        try {
            System.out.println("strict: "
                    + client.send(strict, HttpResponse.BodyHandlers.discarding()).version());
        } catch (IOException noHttp3) {
            System.out.println("strict failed: " + noHttp3);
        }
    }
}

go deeper

for a junior

Recall that HTTP/3 arrived in the standard client in JDK 26, that you ask for it with HttpClient.Version.HTTP_3, and that HTTP/2 is still what a client prefers by default.

for a middle

Explain why discovery exists: QUIC runs on UDP, so nothing can upgrade from TCP. Contrast a request-level preference, a client-level preference and the ALT_SVC and HTTP_3_URI_ONLY hints, and name response.version() as the check.

for a senior

Show what you would verify before relying on it: whether UDP reaches the server, whether a proxy is selected, how a short request timeout interacts with the fallback window, and what your logs report from response.version().

for a principal

The decision is whether to opt a fleet in at all. Weigh gains on lossy networks against fallback latency, proxied routes that never use it, and egress rules for UDP, and roll it out per client while measuring the protocol actually used.

## What changed, and what did not **HTTP/3** is the successor to HTTP/2. It keeps HTTP's requests and responses but runs on **QUIC**, a reliable transport built on UDP datagrams and secured with TLS 1.3, rather than on TCP. JEP 517 lists the expected gains as potentially faster handshakes, avoiding network congestion issues such as head-of-line blocking, and more reliable transport where packet loss is high. JEP 517 made it available in `java.net.http` in JDK 26 with minimal API change: - **The default did not move.** A client still prefers HTTP/2, and HTTP/3 is opt-in. - **Sending code did not change.** `send`, `sendAsync` and the body handlers work the same way. - **The surface stayed small.** There is no public QUIC API, no server-side HTTP/3, and the legacy `java.net.URL` handler stays on HTTP/1.1. - **TLS is narrower.** The first implementation supports only the default secure-socket provider, SunJSSE. ## Asking for it The preference can sit on the client, for every request it sends, or on one request: ```java HttpClient client = HttpClient.newBuilder() .version(HttpClient.Version.HTTP_3) .build(); HttpRequest request = HttpRequest.newBuilder(uri) .version(HttpClient.Version.HTTP_3) .build(); ``` A request's own version wins over the client's, which applies only when the request has none. Either way this is a preference, so check `HttpResponse.version()` for what was used. ## Why discovery is the hard part An HTTP/2 connection can be negotiated during the TLS handshake on TCP, but TCP cannot turn into QUIC: HTTP/3 runs on UDP, so an existing connection cannot be upgraded, and a client cannot tell in advance whether a server supports it. Which strategy you get depends on where the preference sits and on the `HttpOption.H3_DISCOVERY` hint, set with `HttpRequest.Builder.setOption`: | Configuration | What the client does | What it costs | |---|---|---| | Request `HTTP_3`, no hint | Tries HTTP/3 first, falls back if it fails or times out | Waits on a server without HTTP/3 | | Client `HTTP_3`, request unset, no hint | Races HTTP/3 against TCP, uses the first to succeed | May open an HTTP/3 connection it never uses | | Hint `ALT_SVC` | Stays on HTTP/2 or HTTP/1.1 until the server advertises an `h3` alternative service | The first requests are not HTTP/3 | | Hint `HTTP_3_URI_ONLY` | Attempts only HTTP/3 at the URI's host and port, with no fallback | Works only if you know the server supports it | The remaining `Http3DiscoveryMode` value, `ANY`, is what the JDK applies when no hint is given. The hint has no effect unless HTTP/3 is preferred on the client or the request; a request that sets `HTTP_3_URI_ONLY` with neither gets an ordinary response. ## Where the preference does not hold - **Scheme:** a request whose scheme is not `https` is never sent over HTTP/3. A request with `http://` and a preference gets HTTP/1.1; adding `HTTP_3_URI_ONLY` fails with `UnsupportedProtocolVersionException`. - **Proxy:** in this implementation HTTP/3 is not used when a proxy is selected. The request downgrades, and with `HTTP_3_URI_ONLY` it fails. - **TLS configuration:** HTTP/3 needs TLS 1.3. With `SSLParameters` that allow only TLS 1.2, `build()` throws an `UncheckedIOException` caused by `UnsupportedProtocolVersionException` when the client prefers HTTP/3, while a request-level preference on such a client quietly uses HTTP/1.1. - **WebSocket:** the opening handshake is pinned to HTTP/1.1 by the internal `OpeningHandshake` class, so an HTTP/3 preference does not reach it. ## Timeouts and failure The JDK's request-level strategy gives the direct HTTP/3 attempt a window of 2750 ms by default, or the client's `connectTimeout` when that is shorter. The default and its system property, `jdk.httpclient.http3.maxDirectConnectionTimeout`, are undocumented internals of this JDK, absent from the module's documented property list. The effects on JDK 27.0.1, against a local HTTPS server with no HTTP/3: - The first request took about 2.8 seconds to fall back, and a second on the same client took about 1 ms. A client-level preference, which races, answered in about 16 ms. - A request `timeout` of 1 second, shorter than the window, ended in `HttpConnectTimeoutException` instead of falling back. - A client `connectTimeout` of 1 second instead shortened the window, and the request fell back in about 1 second. `HTTP_3_URI_ONLY` needs a timeout too. Against the same server it failed with `ConnectException` only after about a minute, and with a 2-second timeout it failed with `HttpConnectTimeoutException` in 2 seconds. ## Versions `HttpClient.Version.HTTP_3`, `HttpOption`, `HttpRequest.Builder.setOption`, `HttpRequest.getOption` and `UnsupportedProtocolVersionException` are all `@since 26`, and JEP 517 shipped in 26 with no preview stage. At JDK 25 the enum holds only `HTTP_1_1` and `HTTP_2`, so code naming `HTTP_3` does not compile there.

  • Why can java.net.http not upgrade a running HTTP/2 connection to HTTP/3?
    HTTP/1.1 and HTTP/2 run on TCP streams and HTTP/3's QUIC runs on UDP datagrams, so there is nothing to upgrade. That is why the client has to try HTTP/3 first, race it against TCP, or learn of an `h3` endpoint from an HTTP Alternative Services advertisement on an earlier response.
  • What can happen when a java.net.http request prefers HTTP/3 and sets a very short timeout?
    It can fail instead of falling back. This JDK gives the direct HTTP/3 attempt about 2.75 seconds by default, an undocumented internal, and on JDK 27.0.1 a 1-second request timeout against an HTTPS server with no HTTP/3 ended in `HttpConnectTimeoutException`. Use a longer timeout, a client `connectTimeout` below it, which shrinks the window, a client-level preference so the protocols race, or `ALT_SVC`.
  • Where does UnsupportedProtocolVersionException appear when a java.net.http client cannot use HTTP/3?
    The Javadoc names two places. Building a client that prefers HTTP/3 may fail, and in the JDK's implementation it arrives as the cause of an `UncheckedIOException`, which `build()` documents. Sending a request with `HTTP_3_URI_ONLY` fails with it directly. A request-level preference without that hint simply downgrades on such a client.

  • Since JDK 26 java.net.http uses HTTP/3 by default whenever the server supports it.
  • Setting version(HTTP_3) guarantees that the exchange runs over HTTP/3.
  • Turning on HTTP/3 means rewriting calls to send, sendAsync and the body handlers.
  • HTTP_3_URI_ONLY falls back to HTTP/2 when the server has no HTTP/3 listener.
  • The client upgrades a running HTTP/2 connection to HTTP/3 the way HTTP/1.1 upgrades to HTTP/2.
  • JDK 26 also added a public QUIC API and a server-side HTTP/3 implementation.

HTTP/3 in the HTTP Client API (HttpClient.Version.HTTP_3)
Java 26
HttpOption.H3_DISCOVERY and Http3DiscoveryMode
Java 26
HttpRequest.Builder.setOption
Java 26
UnsupportedProtocolVersionException
Java 26

Assumes Java 27; HTTP/3 support arrived in Java 26, and at Java 25 HttpClient.Version has no HTTP_3 constant.

context