--- title: HTTP/3 (QUIC) Support description: Experimental HTTP/3 over QUIC support in MockServer, enabled via the http3Port configuration property. HTTP/3 requests are routed through the full expectation matching pipeline. shortTitle: HTTP/3 layout: page pageOrder: 12 section: 'Mock Server' subsection: true sitemap: priority: 0.6 changefreq: 'monthly' lastmod: 2026-06-01T14:00:00+00:00 ---
EXPERIMENTAL — HTTP/3 support is fully integrated with MockServer's request pipeline but is labelled experimental because the underlying QUIC transport is a Netty incubator dependency (pre-release artifact). HTTP/3 is off by default and must be explicitly enabled.

MockServer can optionally accept HTTP/3 requests over QUIC (UDP). HTTP/3 is the third major version of the HTTP protocol, using QUIC as the transport instead of TCP. This is useful when you want to test clients that connect using HTTP/3.

HTTP/3 requests are routed through the same expectation matching pipeline as HTTP/1.1 and HTTP/2 requests. This means all features work the same way: expectation matching, response actions, template actions, recording for verification, and proxy forwarding.

## Enabling HTTP/3

HTTP/3 is disabled by default (http3Port defaults to 0). Set it to a non-zero UDP port number to start the listener:

Method | Example
--- | ---
Java system property | -Dmockserver.http3Port=8443
Environment variable | MOCKSERVER_HTTP3_PORT=8443
Configuration API | Configuration.configuration().http3Port(8443)

When http3Port is 0 (the default), the HTTP/3 listener is not started and has no impact on the existing TCP/HTTP server.

## Lifecycle

When http3Port is configured, the HTTP/3 server starts automatically with MockServer and stops when MockServer shuts down. No separate lifecycle management is needed.

If the native QUIC transport is not available on the platform (see native platform requirement), MockServer logs a warning and continues without HTTP/3. The existing TCP/HTTP server is never affected.

The bound HTTP/3 port can be retrieved programmatically via MockServer.getHttp3Port().

## Native platform requirement

HTTP/3 uses the netty-incubator-codec-http3 library, which requires a native BoringSSL library for the QUIC transport. The native library is included automatically for the following platforms:

- linux-x86_64
- linux-aarch_64
- osx-x86_64
- osx-aarch_64
- windows-x86_64

If the native library cannot be loaded on the current platform, the HTTP/3 server will not start (a warning is logged). The existing TCP/HTTP server is not affected.

## TLS

The HTTP/3 server uses MockServer's configured TLS certificate material — the same private key and certificate chain used by the HTTPS server. This means the TLS configuration properties (privateKeyPath, x509CertificatePath, etc.) apply to HTTP/3 as well.

If no custom certificate is configured, MockServer's auto-generated certificate (created via BouncyCastle) is used, which is suitable for testing.

## What works

- Expectation matching — HTTP/3 requests are matched against expectations identically to HTTP/1.1 and HTTP/2
- Response actions — all response action types (static, template, callback, etc.)
- Request recording — HTTP/3 requests are recorded for verification
- Proxy forwarding — unmatched requests can be forwarded when proxy mode is configured
- Request body — text and binary request bodies are read and matched correctly
- Configurable TLS — uses the same TLS certificate as the HTTPS server
- Lifecycle integration — starts and stops automatically with MockServer
- Fail-soft startup — graceful fallback when native QUIC is unavailable

## Limitations

- Streaming/SSE responses — streaming response bodies (Server-Sent Events, chunked streaming) are not supported over HTTP/3. If an expectation returns a streaming body, MockServer logs a warning and sends only the headers and any static body bytes. Use HTTP/1.1 or HTTP/2 for streaming responses.
- Dashboard visibility — HTTP/3 connections do not appear as a separate protocol in the MockServer dashboard (requests are logged and visible, but the protocol is not distinguished)
- Incubator dependency — the netty-incubator-codec-http3 library is a pre-release artifact; its API may change in future Netty releases