The Fix
Upgrade to version 0.17.5 or later.
Based on closed Kludex/uvicorn issue #1326 · 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%.
@@ -39,12 +39,15 @@ Options:
--reload-include TEXT Set glob patterns to include while watching
for files. Includes '*.py' by default; these
- defaults can be overridden in `--reload-
- exclude`.
+ defaults can be overridden with `--reload-
Option A — Upgrade to fixed release\nUpgrade to version 0.17.5 or later.\nWhen NOT to use: Do not use this fix if watchgod is not installed, as it will not work as intended.\n\n
Why This Fix Works in Production
- Trigger: Interactions between --reload-dir, --reload-include, and --reload-exclude are not very intuitive or well explained (and may even be wrong)
- Mechanism: The documentation did not clarify that --reload-include and --reload-exclude require watchgod to function
- Why the fix works: Addresses documentation deficiencies regarding the `--reload` behaviors in Uvicorn, clarifying that `--reload-include` and `--reload-exclude` options are ignored unless watchgod is installed. (first fixed release: 0.17.5).
- 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.6 in real deployments (not just unit tests).
- The documentation did not clarify that --reload-include and --reload-exclude require watchgod to function
- Surfaces as: File ".../site-packages/watchfiles/main.py", line 118, in watch\n with RustNotify(\n ^^^^^^^^^^^
Proof / Evidence
- GitHub issue: #1326
- Fix PR: https://github.com/kludex/uvicorn/pull/1331
- First fixed release: 0.17.5
- Reproduced locally: No (not executed)
- Last verified: 2026-02-09
- Confidence: 0.75
- Did this fix it?: Yes (upstream fix exists)
- Own content ratio: 0.74
Discussion
High-signal excerpts from the issue thread (symptoms, repros, edge-cases).
“Okay, I might have gotten my understanding of the above wrong as well”
“@posita Thank you for investigating and taking on this issue!! These docs are missing examples for clarity https://www.uvicorn.org/settings/#reloading-with-watchfiles Maybe we can add them?”
“I'll try to put together a PR that proposes more helpful/accessible language. _UPDATE: PR #1331 is up._”
“Awesome investigation and apologies for the wrong advice”
Failure Signature (Search String)
- Interactions between --reload-dir, --reload-include, and --reload-exclude are not very intuitive or well explained (and may even be wrong)
Error Message
Stack trace
Error Message
-------------
File ".../site-packages/watchfiles/main.py", line 118, in watch\n with RustNotify(\n ^^^^^^^^^^^
Environment
- Python: 3.9.6
What Broke
Users experienced confusion and misconfigurations leading to unexpected reload behavior.
Why It Broke
The documentation did not clarify that --reload-include and --reload-exclude require watchgod to function
Fix Options (Details)
Option A — Upgrade to fixed release Safe default (recommended)
Upgrade to version 0.17.5 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/1331
First fixed release: 0.17.5
Last verified: 2026-02-09. Validate in your environment.
When NOT to Use This Fix
- Do not use this fix if watchgod is not installed, as it will not work as intended.
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.17.5 | Fixed |
Related Issues
No related fixes found.
Sources
We don’t republish the full GitHub discussion text. Use the links above for context.