The Fix
Upgrade to version 0.14.0 or later.
Based on closed Kludex/uvicorn issue #1045 · 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%.
@@ -133,6 +133,8 @@ uvicorn.run(app, host="127.0.0.1", port=5000, log_level="info")
or reloading (`reload=True`), so we recommend using the import string style.
+Also note that in this case, you should put `uvicorn.run` into `if __name__ == '__main__'` clause in the main module.
+
## Using a process manager
RuntimeError:
An attempt has been made to start a new process before the
current process has finished its bootstrapping phase.
This probably means that you are not using fork to start your
child processes and you have forgotten to use the proper idiom
in the main module:
if __name__ == '__main__':
freeze_support()
...
The "freeze_support()" line can be omitted if the program
is not going to be frozen to produce an executable.
Re-run the minimal reproduction on your broken version, then apply the fix and re-run.
Option A — Upgrade to fixed release\nUpgrade to version 0.14.0 or later.\nWhen NOT to use: This fix is not applicable if the application does not require reloading or is not run programmatically.\n\n
Why This Fix Works in Production
- Trigger: RuntimeError:
- Mechanism: The error occurs due to the absence of the if __name__ == '__main__' block when using reload=True
- Why the fix works: Added a warning in the documentation regarding the use of the `reload` option with `uvicorn.run`. (first fixed release: 0.14.0).
- 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
- Shows up under Python 3.9.5 in real deployments (not just unit tests).
- The error occurs due to the absence of the if __name__ == '__main__' block when using reload=True
- Surfaces as: RuntimeError:
Proof / Evidence
- GitHub issue: #1045
- Fix PR: https://github.com/kludex/uvicorn/pull/1047
- First fixed release: 0.14.0
- 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.45
Discussion
High-signal excerpts from the issue thread (symptoms, repros, edge-cases).
“if I do python dev.py I have this error which is quite explicit about multiprocessing, since we dont use fork but spawn (see https://docs.python.org/3/library/multiprocessing.html#contexts-and-start-methods) so…”
“I tested the demo on my linux server (CentOS 7)”
“so it seems like it's indeed a macos issue, cant personnally help more on this but I agree the message in this case is not…”
“I think this issue is likely caused by same reason with https://github.com/encode/uvicorn/issues/949. IMO, write something in doc to point the proper idiom in the main…”
Failure Signature (Search String)
- RuntimeError:
Error Message
Stack trace
Error Message
-------------
RuntimeError:
An attempt has been made to start a new process before the
current process has finished its bootstrapping phase.
This probably means that you are not using fork to start your
child processes and you have forgotten to use the proper idiom
in the main module:
if __name__ == '__main__':
freeze_support()
...
The "freeze_support()" line can be omitted if the program
is not going to be frozen to produce an executable.
Minimal Reproduction
RuntimeError:
An attempt has been made to start a new process before the
current process has finished its bootstrapping phase.
This probably means that you are not using fork to start your
child processes and you have forgotten to use the proper idiom
in the main module:
if __name__ == '__main__':
freeze_support()
...
The "freeze_support()" line can be omitted if the program
is not going to be frozen to produce an executable.
Environment
- Python: 3.9.5
What Broke
Running uvicorn programmatically without the main block leads to misleading error messages.
Why It Broke
The error occurs due to the absence of the if __name__ == '__main__' block when using reload=True
Fix Options (Details)
Option A — Upgrade to fixed release Safe default (recommended)
Upgrade to version 0.14.0 or later.
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/1047
First fixed release: 0.14.0
Last verified: 2026-02-09. Validate in your environment.
When NOT to Use This Fix
- This fix is not applicable if the application does not require reloading or is not run programmatically.
Verify Fix
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
- 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.14.0 | Fixed |
Related Issues
No related fixes found.
Sources
We don’t republish the full GitHub discussion text. Use the links above for context.