uvicorn Docs: workers = 1 when WEB_CONCURRENCY is not set

The Fix

Upgrade to version 0.13.4 or later.

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

@@ -45,7 +45,7 @@ Options:
   --workers INTEGER               Number of worker processes. Defaults to the
                                   $WEB_CONCURRENCY environment variable if
-                                  available. Not valid with --reload.
+                                  available, or 1. Not valid with --reload.

fix.md

Option A — Upgrade to fixed release\nUpgrade to version 0.13.4 or later.\nWhen NOT to use: This fix is not applicable if the application requires multiple workers for load balancing.\n\n

Why This Fix Works in Production

Trigger: in https://docs.python.org/3/library/multiprocessing.html#exchanging-objects-between-processes
Mechanism: The documentation did not specify that the default number of workers is 1 when WEB_CONCURRENCY is not set
Why the fix works: Documents the default value of 1 for workers in the Uvicorn documentation, addressing issue #940. (first fixed release: 0.13.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 did not specify that the default number of workers is 1 when WEB_CONCURRENCY is not set
Production symptom (often without a traceback): in https://docs.python.org/3/library/multiprocessing.html#exchanging-objects-between-processes

Proof / Evidence

GitHub issue: #940
Fix PR: https://github.com/kludex/uvicorn/pull/943
First fixed release: 0.13.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.72

Discussion

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

Jump to Sources Open on GitHub

“Thanks! > workers set the number of processes not threads, just to be clear Oh yes, I used "thread-safe" because I'm not sure there's a…”

@pawamoy · 2021-01-21 · source

“> I have an application that must use only one worker (it's not thread-safe), and so I wanted to confirm that, by default, uvicorn only…”

@euri10 · 2021-01-21 · source

“seems like there is :_) Queues are thread and process safe”

@euri10 · 2021-01-21 · source

Failure Signature (Search String)

in https://docs.python.org/3/library/multiprocessing.html#exchanging-objects-between-processes

Copy-friendly signature

signature.txt

Failure Signature
-----------------
in https://docs.python.org/3/library/multiprocessing.html#exchanging-objects-between-processes

Error Message

Signature-only (no traceback captured)

error.txt

Error Message
-------------
in https://docs.python.org/3/library/multiprocessing.html#exchanging-objects-between-processes

What Broke

Users were unaware of the default worker setting, leading to potential misconfigurations.

Why It Broke

The documentation did not specify that the default number of workers is 1 when WEB_CONCURRENCY is not set

Fix Options (Details)

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

Upgrade to version 0.13.4 or later.

When NOT to use: This fix is not applicable if the application requires multiple workers for load balancing.

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

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

First fixed release: 0.13.4

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

When NOT to Use This Fix

This fix is not applicable if the application requires multiple workers for load balancing.

Did This Fix Work in Your Case?

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

Prevention

Capture the exact failing error string in logs and tests so you can reproduce via a minimal script.
Pin production dependencies and upgrade only with a reproducible test that hits the failing path.

Version Compatibility Table

Version	Status
0.13.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 Docs: workers = 1 when WEB_CONCURRENCY is not set (Fix)