uvicorn Uvicorn does not respect gunicorn's keepalive

The Fix

Upgrade to version 0.11.4 or later.

Based on closed Kludex/uvicorn issue #194 · PR/commit linked

Production note: Most teams hit this during upgrades or environment changes. Roll out with a canary and smoke critical endpoints (health, OpenAPI/docs) before 100%.

Jump to Verify Open PR/Commit

@@ -103,7 +103,8 @@ async def create_servers(self, loop):
                 state=state,
                 logger=self.log,
-                ws_protocol_class=WebSocketProtocol
+                ws_protocol_class=WebSocketProtocol,
+                timeout_keep_alive=self.cfg.keepalive

repro.py

Trying 127.0.0.1...
Connected to localhost.
Escape character is '^]'.
HTTP/1.1 200 OK
server: uvicorn
date: Fri, 21 Sep 2018 12:15:40 GMT
content-type: text/plain
transfer-encoding: chunked

d
Hello, world!
0

Connection closed by foreign host.

verify

Re-run the minimal reproduction on your broken version, then apply the fix and re-run.

fix.md

Option A — Upgrade to fixed release\nUpgrade to version 0.11.4 or later.\nWhen NOT to use: This fix should not be applied if using a different server configuration that does not require keep-alive.\n\n

Why This Fix Works in Production

Trigger: Uvicorn does not respect gunicorn's keepalive timeout
Mechanism: Uvicorn does not respect Gunicorn's keep-alive timeout setting during server creation
Why the fix works: Respects Gunicorn's keep-alive timeout by adding a timeout_keep_alive parameter to the server creation process. (first fixed release: 0.11.4).

Production impact:

If left unfixed, the same config can fail only in production (env differences), causing startup failures or partial feature outages.

Why This Breaks in Prod

Uvicorn does not respect Gunicorn's keep-alive timeout setting during server creation
Production symptom (often without a traceback): Uvicorn does not respect gunicorn's keepalive timeout

Proof / Evidence

GitHub issue: #194
Fix PR: https://github.com/kludex/uvicorn/pull/195
First fixed release: 0.11.4
Reproduced locally: No (not executed)
Last verified: 2026-02-09
Confidence: 0.85
Did this fix it?: Yes (upstream fix exists)
Own content ratio: 0.69

Discussion

High-signal excerpts from the issue thread (symptoms, repros, edge-cases).

Jump to Sources Open on GitHub

“If we sleep 10 seconds between requests we can see that uvicorn ignores gunicorn's keep-alive setting:”

Issue thread · issue description · source

Failure Signature (Search String)

Uvicorn does not respect gunicorn's keepalive timeout

Copy-friendly signature

signature.txt

Failure Signature
-----------------
Uvicorn does not respect gunicorn's keepalive timeout

Error Message

Signature-only (no traceback captured)

error.txt

Error Message
-------------
Uvicorn does not respect gunicorn's keepalive timeout

Minimal Reproduction

repro.py

Trying 127.0.0.1...
Connected to localhost.
Escape character is '^]'.
HTTP/1.1 200 OK
server: uvicorn
date: Fri, 21 Sep 2018 12:15:40 GMT
content-type: text/plain
transfer-encoding: chunked

d
Hello, world!
0

Connection closed by foreign host.

What Broke

Requests experience unexpected connection closures due to ignored keep-alive settings.

Why It Broke

Uvicorn does not respect Gunicorn's keep-alive timeout setting during server creation

Fix Options (Details)

Option A — Upgrade to fixed release Safe default (recommended)

Upgrade to version 0.11.4 or later.

When NOT to use: This fix should not be applied if using a different server configuration that does not require keep-alive.

Use when you can deploy the upstream fix. It is usually lower-risk than long-lived workarounds.

Option D — Guard side-effects with OnceOnly Guardrail for side-effects

Mitigate duplicate external side-effects under retries/timeouts/agent loops by gating the operation before calling external systems.

Place OnceOnly between your code/agent and real side-effects (Stripe, emails, CRM, APIs).
Use a stable key per side-effect (e.g., customer_id + action + idempotency_key).
Fail-safe: configure fail-open vs fail-closed based on blast radius and spend risk.

Show example snippet (optional)

onceonly.py

from onceonly import OnceOnly
import os

once = OnceOnly(api_key=os.environ["ONCEONLY_API_KEY"], fail_open=True)

# Stable idempotency key per real side-effect.
# Use a request id / job id / webhook delivery id / Stripe event id, etc.
event_id = "evt_..."  # replace
key = f"stripe:webhook:{event_id}"

res = once.check_lock(key=key, ttl=3600)
if res.duplicate:
    return {"status": "already_processed"}

# Safe to execute the side-effect exactly once.
handle_event(event_id)

See OnceOnly SDK

When NOT to use: Do not use this to hide logic bugs or data corruption. Use it to block duplicate external side-effects and enforce tool permissions/spend caps.

Fix reference: https://github.com/kludex/uvicorn/pull/195

First fixed release: 0.11.4

Last verified: 2026-02-09. Validate in your environment.

When NOT to Use This Fix

This fix should not be applied if using a different server configuration that does not require keep-alive.
Do not use this to hide logic bugs or data corruption. Use it to block duplicate external side-effects and enforce tool permissions/spend caps.

Verify Fix

verify

Re-run the minimal reproduction on your broken version, then apply the fix and re-run.

Did This Fix Work in Your Case?

Quick signal helps us prioritize which fixes to verify and improve.

Prevention

Make timeouts explicit and test them (unit + integration) to avoid silent behavior changes.
Instrument retries (attempt count + reason) and alert on spikes to catch dependency slowdowns.

Version Compatibility Table

Version	Status
0.11.4	Fixed

Related Issues

No related fixes found.

Cluster: uvicorn:configuration-error All hubs All clusters

Related clusters: Data consistency Race condition SSL handshake

Sources

We don’t republish the full GitHub discussion text. Use the links above for context.

uvicorn Uvicorn does not respect gunicorn's keepalive timeout (Fix)