Playwright Python: Resolving net::ERR_HTTP2_PROTOCOL_ERROR on Headless Linux

Root Cause Diagnosis

This error occurs when Chromium’s headless rendering engine negotiates an HTTP/2 connection but fails mid-stream due to a mismatch between the container/VPS network stack and the server’s HTTP/2 flow-control expectations — most commonly triggered by missing or incompatible system libraries (libnss3, libgbm1) on minimal Linux distributions, or by a network layer (Docker bridge, corporate proxy, WAF) that mangles HTTP/2 frames that a full desktop Chrome installation would otherwise tolerate via automatic protocol fallback. It disproportionately affects headless mode because Playwright’s bundled Chromium build omits some system integrations present in a full desktop install, and headless environments frequently run behind NAT/proxy layers not present in local development.

Quick Fix (1-Minute Override)

Force HTTP/1.1 at the browser launch level to bypass the HTTP/2 negotiation entirely:

browser = await playwright.chromium.launch(
    args=["--disable-http2"]
)

If the error disappears, the root cause is confirmed to be HTTP/2-specific and you can proceed to a more targeted fix below rather than staying on HTTP/1.1 permanently (which has performance costs on sites serving large assets).

Step-by-Step Resolution

Step 1: Confirm It’s Environment-Specific, Not Code-Specific

Run the identical script locally (non-headless, non-container) against the same URL:

browser = await playwright.chromium.launch(headless=False)

If it succeeds locally but fails on the server, this confirms a system/network-layer issue rather than a Playwright API misuse issue — proceed to Step 2.

Step 2: Install Missing System Dependencies

On Debian/Ubuntu-based headless servers, missing shared libraries are the most common cause. Install the full dependency set:

sudo apt-get update
python -m playwright install-deps chromium

Or manually, if install-deps is unavailable (e.g., minimal Alpine-based images):

apt-get install -y \
    libnss3 libnspr4 libatk1.0-0 libatk-bridge2.0-0 \
    libcups2 libdrm2 libxkbcommon0 libxcomposite1 \
    libxdamage1 libxfixes3 libxrandr2 libgbm1 libpango-1.0-0 \
    libcairo2 libasound2

Step 3: Disable HTTP/2 Selectively via Launch Args

Rather than globally disabling HTTP/2, restrict it to reduce blast radius on unrelated requests:

browser = await playwright.chromium.launch(
    headless=True,
    args=[
        "--disable-http2",
        "--disable-quic",
        "--disable-features=NetworkService"
    ]
)

Note: --disable-features=NetworkService is a broader fallback and should only be used if --disable-http2 alone does not resolve the error — test incrementally.

Step 4: Check for Docker Bridge Network MTU Mismatch

If running inside Docker, the default bridge network MTU (1500) can conflict with the host’s actual MTU (commonly 1450 on cloud VPS providers using overlay networking), causing HTTP/2 frame fragmentation errors. Check host MTU:

ip link show eth0 | grep mtu

If it differs from Docker’s default, set it explicitly in /etc/docker/daemon.json:

{
  "mtu": 1450
}

Restart Docker:

systemctl restart docker

Step 5: Rule Out TLS/Certificate Interception (Corporate Proxy, WAF)

If the server sits behind a corporate proxy or security appliance performing TLS interception, it may re-terminate HTTP/2 connections improperly. Test bypassing the proxy layer:

browser = await playwright.chromium.launch(
    proxy={"server": "direct://"}
)

If this resolves the error, the proxy/WAF is the actual fault, not Playwright or Chromium — escalate to network administration rather than continuing to patch browser args.

Step 6: Update Playwright and Chromium Together

Version mismatches between Playwright’s Python package and its bundled Chromium binary can cause protocol negotiation bugs fixed in later releases:

pip install --upgrade playwright
python -m playwright install chromium

Confirm the installed Chromium version:

python -m playwright --version

Why This Fails for Some Users

Alpine Linux / musl libc incompatibility: Playwright’s bundled Chromium is built against glibc and does not run reliably on Alpine’s musl libc, even with all dependencies manually installed. install-deps will silently fail or report false success. Use a Debian-slim or Ubuntu base image instead of Alpine for Playwright workloads.
Insufficient /dev/shm size in containers: Default Docker /dev/shm is capped at 64MB, which is unrelated to HTTP/2 directly but causes Chromium to crash mid-render under load, producing HTTP2_PROTOCOL_ERROR as a secondary symptom rather than a network fault. Fix with:docker run --shm-size=1gb ...
Kernel-level QUIC/UDP restrictions on cloud VPS providers: Some budget VPS providers throttle or block UDP traffic used by QUIC (HTTP/3 negotiation attempts that fall back to HTTP/2), and the fallback handshake itself fails rather than cleanly downgrading to HTTP/1.1. Confirm with:curl --http2 -v https://targetsite.com -o /dev/null
Server-side HTTP/2 rate limiting misidentifying headless traffic: Some origin servers or CDNs (Cloudflare, Akamai) apply stricter HTTP/2 stream limits to traffic fingerprinted as automated/headless, closing the connection mid-stream. This presents identically to a client-side bug but requires User-Agent and TLS fingerprint adjustments (playwright-stealth or equivalent) rather than any Nginx or system-level fix.
Outdated kernel TCP congestion control on older VPS images: Legacy CentOS 7 or Ubuntu 18.04 images with outdated kernels (pre-4.9) lack BBR congestion control and can mishandle HTTP/2’s multiplexed stream prioritization under latency, particularly on cross-region requests. Upgrading the kernel or switching congestion control algorithm (sysctl net.ipv4.tcp_congestion_control=bbr) resolves this in edge cases where all software-layer fixes fail.