Alt-Svc HTTP Header — Reference

What it does

Alt-Svc (Alternative Service) tells clients that the origin can be reached via a different protocol, port, or hostname. Its primary real-world use is advertising HTTP/3 (QUIC) support — a server sends Alt-Svc: h3=":443" over HTTP/2, and the browser remembers to use HTTP/3 on future connections to that origin.

It's how the web's protocol upgrade path works without requiring DNS changes or explicit client configuration.

Syntax

Alt-Svc: <protocol-id>="<host>:<port>"[; ma=<max-age>][; persist=1]
Alt-Svc: <alt1>, <alt2>
Alt-Svc: clear

Examples:

Alt-Svc: h3=":443"; ma=86400
Alt-Svc: h3=":443"; ma=86400, h3-29=":443"; ma=86400
Alt-Svc: h3="alt.example.com:8080"; ma=3600
Alt-Svc: clear

Parameters

Parameter	Meaning
`protocol-id`	ALPN protocol identifier (`h3`, `h2`, `h3-29`, etc.)
`host:port`	Alternative host and port. Empty host means same as origin.
`ma`	Max-age in seconds — how long to cache this alternative
`persist=1`	Keep this cached through network changes (useful for mobile)

HTTP/3 advertisement — the main use case

This is what you'll see on virtually every modern site:

Alt-Svc: h3=":443"; ma=86400

h3 — HTTP/3 (QUIC) protocol
:443 — same host, port 443 (same as current connection)
ma=86400 — remember this for 24 hours

The browser sees this on an HTTP/2 response, stores the alternative, and on the next connection attempt to this origin it tries HTTP/3 first. If QUIC is blocked (some corporate firewalls block UDP), it falls back to TCP/HTTP/2 transparently.

Multiple alternatives

Servers often advertise multiple alternatives for different QUIC draft versions:

Alt-Svc: h3=":443"; ma=86400, h3-29=":443"; ma=86400

h3-29 is an older QUIC draft — some clients support it but not the final h3. Listing both maximises upgrade success rate.

`Alt-Svc: clear`

Tells clients to forget all previously advertised alternatives for this origin. Use it if you need to roll back HTTP/3 support immediately:

Alt-Svc: clear

How the upgrade actually works

Browser connects to example.com via HTTP/2 (TCP)
Response includes Alt-Svc: h3=":443"; ma=86400
Browser stores: "example.com supports h3 on port 443 for the next 24h"
Next time browser connects to example.com → attempts HTTP/3 (QUIC/UDP) first
HTTP/3 connects successfully → all subsequent requests over QUIC
HTTP/3 fails (UDP blocked) → falls back to HTTP/2 silently

The user never sees any of this. The first connection is always HTTP/2; upgrades happen on subsequent connections.

Cloudflare and Alt-Svc

If your site is behind Cloudflare with HTTP/3 enabled, Cloudflare automatically sets:

Alt-Svc: h3=":443"; ma=86400

You don't need to configure anything — it just appears on your responses. Check with curl -I https://yoursite.com | grep alt-svc.

Enabling HTTP/3 in nginx (with QUIC support)

server {
    listen 443 quic reuseport;
    listen 443 ssl;

    add_header Alt-Svc 'h3=":443"; ma=86400';
}

nginx with QUIC support (available in nginx 1.25+) handles the QUIC transport; Alt-Svc tells clients it's available.

Common mistakes and gotchas

Setting Alt-Svc without actually supporting the protocol. If you advertise h3 but your server doesn't support QUIC, clients will attempt QUIC connections, fail, and fall back — wasting latency on every connection. Only advertise what you support.

Forgetting UDP/443 is open. HTTP/3 runs over QUIC which uses UDP. Many firewalls block UDP/443. If you enable HTTP/3, test from multiple network environments. Alt-Svc will advertise QUIC but clients on restricted networks will always fall back to TCP.

Not setting ma high enough. A low ma (say, 60 seconds) means the browser has to rediscover the alternative on almost every visit. Set it to at least a few hours (ma=86400 is standard).

Real-world examples

Cloudflare response:

HTTP/2 200
alt-svc: h3=":443"; ma=86400
cf-cache-status: HIT

Self-hosted nginx with QUIC:

HTTP/2 200
Alt-Svc: h3=":443"; ma=86400, h3-29=":443"; ma=86400

Rolling back HTTP/3:

HTTP/2 200
Alt-Svc: clear

FAQ

Does Alt-Svc work for HTTP/2 too?

Yes — servers can advertise HTTP/2 as an alternative to HTTP/1.1 via Alt-Svc: h2=":443". In practice this is rare because TLS ALPN negotiation handles HTTP/2 upgrades more cleanly. Alt-Svc is primarily interesting for HTTP/3 because QUIC uses UDP and can't be negotiated via the same ALPN mechanism as TCP protocols.

Can I see if my browser is using the alternative?

In Chrome: open DevTools → Network tab → right-click the columns header → enable "Protocol". You'll see h3 for connections using HTTP/3 vs h2 for HTTP/2. Also check chrome://net-internals/#quic for QUIC session details.

Is Alt-Svc the same as the Upgrade header?

No. Upgrade switches the current TCP connection to a different protocol (used for WebSocket). Alt-Svc advertises that future connections can use a different protocol entirely — including a different transport (UDP instead of TCP). They're complementary but distinct mechanisms.

Fun fact

HTTP/3's adoption path through Alt-Svc is one of the cleverest protocol upgrade strategies in web history. The challenge with deploying a new transport protocol (QUIC/UDP) is the chicken-and-egg problem: clients won't try it if servers don't support it, but servers won't deploy it if clients don't use it. Alt-Svc solved this by making the upgrade invisible and opportunistic — browsers try HTTP/3 if advertised and seamlessly fall back if it fails. This allowed HTTP/3 to go from 0% to over 30% of web traffic within a few years without any user or developer action required.

Alt-Svc proxy response