The Fix
Fixes the handling of reload_dirs to accept a string input, ensuring compatibility with previous functionality.
Based on closed Kludex/uvicorn issue #1266 · 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%.
@@ -119,6 +119,10 @@ def test_reload_dir_is_set(
)
assert config.reload_dirs == [app_dir]
+ config = Config(
+ app="tests.test_config:asgi_app", reload=True, reload_dirs=str(app_dir)
+ )
Option A — Apply the official fix\nFixes the handling of reload_dirs to accept a string input, ensuring compatibility with previous functionality.\nWhen NOT to use: This fix is not applicable if the input should strictly be a list of directories.\n\n
Why This Fix Works in Production
- Trigger: Passing `reload_dirs` as a string instead of a list
- Mechanism: The regression was caused by treating a string as an iterable of characters instead of a single directory path
- 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 regression was caused by treating a string as an iterable of characters instead of a single directory path
- Production symptom (often without a traceback): @Roang-zero1 @euri10 @Kludex this PR introduced a regression and deleted the test for it (`test_reload_dir_is_set()`). Previously you could pass `reload_dirs` a string instead of a list. Now:
Proof / Evidence
- GitHub issue: #1266
- Fix PR: https://github.com/kludex/uvicorn/pull/1267
- Reproduced locally: No (not executed)
- Last verified: 2026-02-11
- Confidence: 0.60
- Did this fix it?: Yes (upstream fix exists)
- Own content ratio: 0.75
Discussion
High-signal excerpts from the issue thread (symptoms, repros, edge-cases).
“@Roang-zero1 @euri10 @Kludex this PR introduced a regression and deleted the test for it (test_reload_dir_is_set()). Previously you could pass reload_dirs a string instead of a list. Now: prints: https://github.com/encode/uvicorn/pull/820/f”
Failure Signature (Search String)
- Passing `reload_dirs` as a string instead of a list
Copy-friendly signature
Failure Signature
-----------------
@Roang-zero1 @euri10 @Kludex this PR introduced a regression and deleted the test for it (`test_reload_dir_is_set()`). Previously you could pass `reload_dirs` a string instead of a list. Now:
Error Message
Signature-only (no traceback captured)
Error Message
-------------
@Roang-zero1 @euri10 @Kludex this PR introduced a regression and deleted the test for it (`test_reload_dir_is_set()`). Previously you could pass `reload_dirs` a string instead of a list. Now:
What Broke
Passing a string to reload_dirs results in warnings and failure to watch the intended directory.
Why It Broke
The regression was caused by treating a string as an iterable of characters instead of a single directory path
Fix Options (Details)
Option A — Apply the official fix
Fixes the handling of reload_dirs to accept a string input, ensuring compatibility with previous functionality.
Fix reference: https://github.com/kludex/uvicorn/pull/1267
Last verified: 2026-02-11. Validate in your environment.
When NOT to Use This Fix
- This fix is not applicable if the input should strictly be a list of directories.
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.
Related Issues
No related fixes found.
Sources
We don’t republish the full GitHub discussion text. Use the links above for context.