NGINX QUIC reuseport: HTTP/3 Silently Breaks Without It

Your NGINX serves HTTP/3 with multiple workers and everything looks fine. It is not fine. The NGINX QUIC reuseport flag is missing from your config, and without it roughly a third of HTTP/3 connections silently fail and fall back to HTTP/2. The fix: add reuseport to exactly one listen ... quic directive per address, then restart NGINX (not reload).

Nothing appears in the error log. Your monitoring, if it checks protocols at all, reports occasional “downgrades” that look like client-side noise. This article shows the one command that diagnoses the problem, the exact fix, and the SELinux trap waiting behind the next directive you will want to enable (quic_bpf).

We hit this on our own infrastructure on 2026-09-09, with days of real production numbers to show for it. Every command and config below was then re-verified from scratch on a clean Rocky Linux 10 VM.

Get an NGINX build that speaks HTTP/3

Stock RHEL-family nginx packages ship without HTTP/3. The GetPageSpeed NGINX Extras repository packages NGINX with HTTP/3 enabled, plus the SELinux policy that makes quic_bpf work (more on that below).

RHEL / CentOS / AlmaLinux / Rocky Linux / Amazon Linux

sudo dnf install https://extras.getpagespeed.com/release-latest.rpm
sudo dnf install nginx

Debian / Ubuntu

First, set up the GetPageSpeed APT repository, then:

sudo apt-get update
sudo apt-get install nginx

Full platform-specific walkthroughs: RHEL-family HTTP/3 setup and Ubuntu/Debian HTTP/3 setup.

The symptom: HTTP/3 that only mostly works

Here is what the failure looked like on our production server over 24 hours, from persisted uptime-check rows:

H3_REQUEST_CANCELLED (local)          275
received a stateless reset             61
timeout: no recent network activity    33
context deadline exceeded              28

Between 28% and 40% of HTTP/3 checks fell back to HTTP/2, in bursts, for days. The NGINX error log showed nothing at any log level. The only external signal was our uptime monitor emailing hourly “HTTP Protocol Downgrade” alerts.

The trap is that HTTP/3 negotiation is designed to fail gracefully. When a QUIC connection dies mid-handshake or mid-stream, the browser or client quietly retries over HTTP/2. Users get slower connections, not error pages. You lose the protocol you deployed, and nobody tells you.

Root cause: one UDP socket, four workers

TCP listeners tolerate a missing reuseport because each TCP connection gets its own socket after accept(). QUIC has no accept step. All datagrams for all connections arrive on the listening UDP socket itself, and NGINX tracks which worker owns which QUIC connection in userspace.

Without reuseport, all workers share a single UDP socket. Whichever worker wakes up first grabs the next datagram, regardless of whether it owns that connection. A worker that receives a mid-connection datagram for a connection it does not own has two options, both bad:

1. Drop it. The stream stalls until the client gives up (H3_REQUEST_CANCELLED, idle timeouts).
2. Reply with a QUIC stateless reset when quic_host_key is configured, actively killing a healthy connection.

Therefore the NGINX QUIC reuseport flag is not a performance optimization. It is a correctness requirement whenever worker_processes is greater than 1. With reuseport, the kernel gives each worker its own socket and consistently routes each connection’s datagrams to the same socket.

On a clean Rocky Linux 10 VM with 4 workers and no reuseport, 13 out of 40 curl --http3-only requests failed: a 32.5% failure rate, matching what we saw in production.

The one-command diagnosis

One command tells you if you have this problem:

ss -ulnp 'sport = :443'

Broken (one UDP socket, shared by every worker):

UNCONN 0 0  0.0.0.0:443  0.0.0.0:*  users:(("nginx",pid=17547,fd=7),("nginx",pid=17546,fd=7),("nginx",pid=17545,fd=7),("nginx",pid=17544,fd=7),("nginx",pid=17543,fd=7))

Correct (one line per worker, four workers = four sockets):

UNCONN 0 0  0.0.0.0:443  0.0.0.0:*  users:(("nginx",pid=17742,fd=11),...)
UNCONN 0 0  0.0.0.0:443  0.0.0.0:*  users:(("nginx",pid=17742,fd=10),...)
UNCONN 0 0  0.0.0.0:443  0.0.0.0:*  users:(("nginx",pid=17742,fd=9),...)
UNCONN 0 0  0.0.0.0:443  0.0.0.0:*  users:(("nginx",pid=17742,fd=7),...)

Count the lines. One UNCONN line with worker_processes greater than 1 means roughly (N-1)/N of your mid-connection datagrams are landing on the wrong worker.

The fix: reuseport on exactly one listener per address

Add reuseport to the QUIC listener of exactly one server block per listen address:

server {
    listen 443 quic reuseport;
    listen 443 ssl;
    http2 on;
    server_name example.com;

    ssl_certificate     /etc/nginx/ssl/example.crt;
    ssl_certificate_key /etc/nginx/ssl/example.key;
    ssl_protocols       TLSv1.2 TLSv1.3;

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

    root /usr/share/nginx/html;
}

Every other virtual host sharing that address must say listen 443 quic; without any options. Listen options in NGINX belong to the address, not the virtual host, and specifying them twice is a config error:

nginx: [emerg] duplicate listen options for 0.0.0.0:443 in /etc/nginx/conf.d/second.conf:2

This “exactly once” rule is a classic infrastructure-as-code trap. Our incident happened because the template that carried the reuseport flag was assigned to a virtual host whose generator could not render it, and the flag silently evaporated fleet-wide. If Ansible or Terraform renders your NGINX configs, add a check that grep -c reuseport across the rendered config equals the number of listen addresses. For the rest of the TLS block, follow our TLS hardening guide.

Adding reuseport requires a restart, not a reload

This is the step that makes people conclude the fix “didn’t work”. After nginx -s reload, the old non-reuseport socket stays open, inherited by the new worker generation, and keeps stealing datagrams. Measured on the VM:

So the sequence is:

sudo nginx -t
sudo systemctl restart nginx
ss -ulnp 'sport = :443'   # verify: one line per worker

On our production host, going from a shared socket to per-worker sockets took the fallback rate from ~30% to 0 in 92 consecutive checks.

Note that reload has a separate HTTP/3 problem: with quic_bpf on, every reload silently kills new QUIC handshakes on stale sockets. That is an upstream bug F5 has not merged a fix for, and our packages patch it. Details: NGINX HTTP/3 is broken after reload.

A fallback is not proof the server stopped offering HTTP/3

When you investigate, check the response headers of the HTTP/2 fallback itself:

curl -sk --http2 -D- -o /dev/null https://example.com/ | grep -i alt-svc
alt-svc: h3=":443"; ma=86400

If Alt-Svc still advertises h3, the server still offers HTTP/3; the client simply could not complete a QUIC exchange. That distinction matters for monitoring: alerting on “protocol downgrade” alone produces false alarms, because transport-level QUIC failures (stateless resets, cancelled requests) happen while the h3 advertisement is perfectly healthy. Ours did exactly that, hourly, for days.

Also verify from outside your network. UDP 443 is its own firewall rule, and a host-local check never exercises it. We found one server where HTTP/3 had never worked externally at all, because the firewall allowed only TCP 443; every local probe was green. The honest probe is:

curl --http3-only -sv https://example.com/ -o /dev/null

from a machine that is not the server itself. On RHEL-family systems, firewall-cmd --list-services must include http3 (or an explicit UDP 443 rule).

The next trap: quic_bpf dies under SELinux

Once reuseport works, you will read about quic_bpf on;, the main-context directive that preserves QUIC connections across binary upgrades and enables connection migration. On RHEL-family systems with SELinux enforcing, enabling it kills NGINX at startup:

[alert] failed to create BPF map (13: Permission denied)
[emerg] ngx_quic_bpf_module failed to initialize, check limits

The message says “check limits”, pointing you at RLIMIT_MEMLOCK. That is the wrong tree. Errno 13 is EACCES, the signature of an LSM denial; a capability or memlock failure returns EPERM instead. The real cause: NGINX runs as httpd_t, and the distribution’s SELinux policy grants httpd_t nothing on the bpf class. Worse, the denial is dontaudit-suppressed, so ausearch -m avc comes back empty and the audit log looks clean. We verified this on Rocky Linux 10: nginx down, errno 13, zero AVC records.

Our packages ship the fix. NGINX 1.30.4-68 and later (and nginx-mod 1.30.4-66 and later) include the nginx-gps SELinux module with all required bpf, capability2 and net_admin permissions behind a default-off boolean. Enable it with:

sudo setsebool -P nginx_quic_bpf 1
sudo systemctl restart nginx

The restart matters here too: the BPF map is created by the master process at startup. After enabling, verify with sudo bpftool map list, which should show a sockhash map, and confirm HTTP/3 still answers with curl --http3-only.

One caveat if you run an older package (nginx before 1.30.5-69, nginx-mod before 1.30.5-67): those shipped the policy as a binary .pp compiled by a newer SELinux toolchain, and a system whose libsepol was even one update level older silently failed to load it. Current packages ship the module as version-agnostic CIL, so it installs on any userland level. If getsebool nginx_quic_bpf reports the boolean does not exist, simply update the package. If you must stay on the older one, update the SELinux userland and load the module manually:

sudo dnf update libsepol libsemanage policycoreutils
sudo semodule -i /usr/share/selinux/targeted/nginx-gps.pp

If you run config linting in CI, Gixy has a dedicated quic-bpf-reuseport check that catches the related reload-time hazard automatically.

Related HTTP/3 issues

• NGINX HTTP/3 is broken after reload covers the stale-socket reload bug and the patch we ship.
• NGINX $http_host is empty on HTTP/3 covers a request-variable bug we patched ahead of upstream.
• Enable NGINX HTTP/3 on RHEL-family and on Ubuntu/Debian for first-time setup.

Conclusion

A protocol that fails silently deserves monitoring that does not. The config you just fixed can quietly regress with the next template render or package change. GetPageSpeed Amplify runs scheduled gixy scans across every host and ties findings to live NGINX runtime metrics. Drop-in compatible with the deprecated nginx-amplify-agent (EOL January 2026).

Multi-worker HTTP/3 without reuseport is not slow, it is broken, and it is broken in the one way nothing logs. The NGINX QUIC reuseport rule is short: one flag per listen address, restart after adding it, and count the lines in ss -ulnp 'sport = :443'. Then, if you want QUIC connection migration and seamless binary upgrades, enable the nginx_quic_bpf boolean that ships with our packages instead of fighting SELinux by hand.

Subscribe to the GetPageSpeed repository for NGINX with HTTP/3, the SELinux policy that makes it operable on enterprise Linux, and 1,000+ other performance-focused packages.