uvicorn Unclear documentation about limit

The Fix

Upgrade to version 0.11.4 or later.

Based on closed Kludex/uvicorn issue #1811 · 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%.

Open PR/Commit

@@ -69,6 +69,8 @@ Options:
                                   tasks to allow, before issuing HTTP 503
                                   responses.
+  --backlog INTEGER               Maximum number of connections to hold in
+                                  backlog
   --limit-max-requests INTEGER    Maximum number of requests to service before

fix.md

Option A — Upgrade to fixed release\nUpgrade to version 0.11.4 or later.\nWhen NOT to use: This fix is not applicable if the documentation is already clear and accurate.\n\n

Why This Fix Works in Production

Trigger: According to the doc, **limit_concurrency** is the maximum number of concurrent connections and any extra connection requests will get 503; **backlog** is the…
Mechanism: The documentation regarding limit_concurrency and backlog settings was unclear and misleading
Why the fix works: Adds support for backlog configuration in Uvicorn, clarifying the documentation regarding limit_concurrency and backlog settings. (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

The documentation regarding limit_concurrency and backlog settings was unclear and misleading
Production symptom (often without a traceback): According to the doc, **limit_concurrency** is the maximum number of concurrent connections and any extra connection requests will get 503; **backlog** is the maximum number of connections in the backlog waiting to be handled.

Proof / Evidence

GitHub issue: #1811
Fix PR: https://github.com/encode/uvicorn/pull/545
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.64

Discussion

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

Jump to Sources Open on GitHub

“I didnt read your answer, I was answering OP ;)”

@euri10 · 2022-12-21 · source

“PR is always welcome to improve documentation...”

@Kludex · 2022-12-18 · source

“@Kludex those are my questions though, once I understand the answers I'm happy to improve the documentation”

@siminchengithub · 2022-12-18 · source

“limit_concurrency docs seem to be off-by-one”

@chaselambda · 2022-12-21 · source

Failure Signature (Search String)

According to the doc, **limit_concurrency** is the maximum number of concurrent connections and any extra connection requests will get 503; **backlog** is the maximum number of
1. when **limit_concurrency** is reached, do all extra requests get 503 straight without being put in the backlog first?

Copy-friendly signature

signature.txt

Failure Signature
-----------------
According to the doc, **limit_concurrency** is the maximum number of concurrent connections and any extra connection requests will get 503; **backlog** is the maximum number of connections in the backlog waiting to be handled.
1. when **limit_concurrency** is reached, do all extra requests get 503 straight without being put in the backlog first?

Error Message

Signature-only (no traceback captured)

error.txt

Error Message
-------------
According to the doc, **limit_concurrency** is the maximum number of concurrent connections and any extra connection requests will get 503; **backlog** is the maximum number of connections in the backlog waiting to be handled.
1. when **limit_concurrency** is reached, do all extra requests get 503 straight without being put in the backlog first?

What Broke

Users experienced confusion leading to improper configuration and potential service disruptions.

Why It Broke

The documentation regarding limit_concurrency and backlog settings was unclear and misleading

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 is not applicable if the documentation is already clear and accurate.

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

Fix reference: https://github.com/encode/uvicorn/pull/545

First fixed release: 0.11.4

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

When NOT to Use This Fix

This fix is not applicable if the documentation is already clear and accurate.

Did This Fix Work in Your Case?

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

Prevention

Add a stress test that runs high-concurrency workloads and fails on thread dumps / blocked locks.
Enable watchdog dumps in prod (faulthandler, thread dump endpoint) to capture deadlocks quickly.

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 Unclear documentation about limit_concurrency and backlog settings (Fix)