uvicorn Unexcepted behavior while reloading (Fix)

The Fix

Upgrade to version 0.30.0 or later.

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

Jump to Verify Open PR/Commit

@@ -75,5 +75,10 @@ def subprocess_started(
     config.configure_logging()
 
-    # Now we can call into `Server.run(sockets=sockets)`
-    target(sockets=sockets)
+    try:

repro.py

INFO:     Shutting down
INFO:     Waiting for application shutdown.
INFO:     Application shutdown complete.
INFO:     Finished server process [3608]
Process SpawnProcess-2:
Traceback (most recent call last):
  File "C:\Users\AppData\Local\Programs\Python\Python310\lib\multiprocessing\process.py", line 314, in _bootstrap
    self.run()
  File "C:\Users\AppData\Local\Programs\Python\Python310\lib\multiprocessing\process.py", line 108, in run
    self._target(*self._args, **self._kwargs)
  File "C:\Users\backend\env\lib\site-packages\uvicorn\_subprocess.py", line 78, in subprocess_started
    target(sockets=sockets)
  File "C:\-backend\env\lib\site-packages\uvicorn\server.py", line 65, in run
    return asyncio.run(self.serve(sockets=sockets))
  File "C:\Users\AppData\Local\Programs\Python\Python310\lib\asyncio\runners.py", line 44, in run
    return loop.run_until_complete(main)
  File "C:\Users\AppData\Local\Programs\Python\Python310\lib\asyncio\base_events.py", line 633, in run_until_complete
    self.run_forever()
  File "C:\Users\AppData\Local\Programs\Python\Python310\lib\asyncio\base_events.py", line 600, in run_forever
    self._run_once()
  File "C:\Users\AppData\Local\Programs\Python\Python310\lib\asyncio\base_events.py", line 1896, in _run_once
    handle._run()
  File "C:\UsersAppData\Local\Programs\Python\Python310\lib\asyncio\events.py", line 80, in _run
    self._context.run(self._callback, *self._args)
  File "C:\-backend\env\lib\site-packages\uvicorn\server.py", line 68, in serve
    with self.capture_signals():
  File "C:\Users\AppData\Local\Programs\Python\Python310\lib\contextlib.py", line 142, in __exit__
    next(self.gen)
  File "C:\backend\env\lib\site-packages\uvicorn\server.py", line 328, in capture_signals
    signal.raise_signal(captured_signal)
KeyboardInterrupt
INFO:     Started server process [8232]
INFO:     Waiting for application startup.
INFO:     Application startup complete.

verify

Re-run the minimal reproduction on your broken version, then apply the fix and re-run.

fix.md

Option A — Upgrade to fixed release\nUpgrade to version 0.30.0 or later.\nWhen NOT to use: This fix should not be used if the application relies on the traceback for debugging.\n\n

Why This Fix Works in Production

Trigger: Process SpawnProcess-2:
Mechanism: The traceback during shutdown is caused by signal propagation in the updated version
Why the fix works: Suppresses noise and dirt from signal propagation introduced in #1600, fixing the traceback issue reported in #2294. (first fixed release: 0.30.0).

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

Shows up under Python 3.10.6 in real deployments (not just unit tests).
The traceback during shutdown is caused by signal propagation in the updated version
Surfaces as: INFO: Shutting down

Proof / Evidence

GitHub issue: #2294
Fix PR: https://github.com/kludex/uvicorn/pull/2317
First fixed release: 0.30.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.22

Discussion

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

Jump to Sources Open on GitHub

“> Exactly I have been experiencing this since whenever I restart my FastAPI application, it doesnt restart gracefully but logs this exact message like yours…”

@TahaAhvazi · 2024-04-01 · source

“Just to add my me too here, me too. Windows machine, PyEnv en Poetry, tried 3 python versions 3.9/3.11/3.12 all same issue. Rolling back to…”

@johanboekhoven · 2024-04-17 · source

“The error occurs only in 0.29.0, but 0.28.1 just works fine.”

@sotasan · 2024-04-19 · source

“@maxfischer2781 I've run both 0.29.0 and https://github.com/maxfischer2781/uvicorn/tree/suppress-signal-traceback via poetry and your basic test.py. Result is your fix works fine on this sample (first output below)…”

@johanboekhoven · 2024-05-02 · source

Failure Signature (Search String)

Process SpawnProcess-2:

Error Message

Stack trace

error.txt

Error Message
-------------
INFO:     Shutting down
INFO:     Waiting for application shutdown.
INFO:     Application shutdown complete.
INFO:     Finished server process [3608]
Process SpawnProcess-2:
Traceback (most recent call last):
  File "C:\Users\AppData\Local\Programs\Python\Python310\lib\multiprocessing\process.py", line 314, in _bootstrap
    self.run()
  File "C:\Users\AppData\Local\Programs\Python\Python310\lib\multiprocessing\process.py", line 108, in run
    self._target(*self._args, **self._kwargs)
  File "C:\Users\backend\env\lib\site-packages\uvicorn\_subprocess.py", line 78, in subprocess_started
    target(sockets=sockets)
  File "C:\-backend\env\lib\site-packages\uvicorn\server.py", line 65, in run
    return asyncio.run(self.serve(sockets=sockets))
  File "C:\Users\AppData\Local\Programs\Python\Python310\lib\asyncio\runners.py", line 44, in run
    return loop.run_until_complete(main)
  File "C:\Users\AppData\Local\Programs\Python\Python310\lib\asyncio\base_events.py", line 633, in run_until_complete
    self.run_forever()
  File "C:\Users\AppData\Local\Programs\Python\Python310\lib\asyncio\base_events.py", line 600, in run_forever
    self._run_once()
  File "C:\Users\AppData\Local\Programs\Python\Python310\lib\asyncio\base_events.py", line 1896, in _run_once
    handle._run()
  File "C:\UsersAppData\Local\Programs\Python\Python310\lib\asyncio\events.py", line 80, in _run
    self._c
... (truncated) ...

Stack trace

error.txt

Error Message
-------------
Jhn in F:\_test_projects\uvicorn λ poetry update uvicorn
Updating dependencies
Resolving dependencies... (0.1s)

Package operations: 0 installs, 1 update, 0 removals

  - Updating uvicorn (0.29.0 cf88d65 -> 0.29.0)

Writing lock file
Jhn in F:\_test_projects\uvicorn λ poetry run python -m uvicorn test:dummy_app --reload
INFO:     Will watch for changes in these directories: ['F:\\_test_projects\\uvicorn']
INFO:     Uvicorn running on http://127.0.0.1:8000 (Press CTRL+C to quit)
INFO:     Started reloader process [54420] using StatReload
INFO:     Started server process [44236]
INFO:     Waiting for application startup.
INFO:     Application startup complete.
INFO:     Shutting down
INFO:     Waiting for application shutdown.
INFO:     Application shutdown complete.
INFO:     Finished server process [44236]
Process SpawnProcess-1:
Traceback (most recent call last):
  File "C:\Users\Jhn\.pyenv\pyenv-win\versions\3.9.10\lib\multiprocessing\process.py", line 315, in _bootstrap
    self.run()
  File "C:\Users\Jhn\.pyenv\pyenv-win\versions\3.9.10\lib\multiprocessing\process.py", line 108, in run
    self._target(*self._args, **self._kwargs)
  File "F:\_test_projects\uvicorn\.venv\lib\site-packages\uvicorn\_subprocess.py", line 78, in subprocess_started
    target(sockets=sockets)
  File "F:\_test_projects\uvicorn\.venv\lib\site-packages\uvicorn\server.py", line 65, in run
    return
... (truncated) ...

Minimal Reproduction

repro.py

INFO:     Shutting down
INFO:     Waiting for application shutdown.
INFO:     Application shutdown complete.
INFO:     Finished server process [3608]
Process SpawnProcess-2:
Traceback (most recent call last):
  File "C:\Users\AppData\Local\Programs\Python\Python310\lib\multiprocessing\process.py", line 314, in _bootstrap
    self.run()
  File "C:\Users\AppData\Local\Programs\Python\Python310\lib\multiprocessing\process.py", line 108, in run
    self._target(*self._args, **self._kwargs)
  File "C:\Users\backend\env\lib\site-packages\uvicorn\_subprocess.py", line 78, in subprocess_started
    target(sockets=sockets)
  File "C:\-backend\env\lib\site-packages\uvicorn\server.py", line 65, in run
    return asyncio.run(self.serve(sockets=sockets))
  File "C:\Users\AppData\Local\Programs\Python\Python310\lib\asyncio\runners.py", line 44, in run
    return loop.run_until_complete(main)
  File "C:\Users\AppData\Local\Programs\Python\Python310\lib\asyncio\base_events.py", line 633, in run_until_complete
    self.run_forever()
  File "C:\Users\AppData\Local\Programs\Python\Python310\lib\asyncio\base_events.py", line 600, in run_forever
    self._run_once()
  File "C:\Users\AppData\Local\Programs\Python\Python310\lib\asyncio\base_events.py", line 1896, in _run_once
    handle._run()
  File "C:\UsersAppData\Local\Programs\Python\Python310\lib\asyncio\events.py", line 80, in _run
    self._context.run(self._callback, *self._args)
  File "C:\-backend\env\lib\site-packages\uvicorn\server.py", line 68, in serve
    with self.capture_signals():
  File "C:\Users\AppData\Local\Programs\Python\Python310\lib\contextlib.py", line 142, in __exit__
    next(self.gen)
  File "C:\backend\env\lib\site-packages\uvicorn\server.py", line 328, in capture_signals
    signal.raise_signal(captured_signal)
KeyboardInterrupt
INFO:     Started server process [8232]
INFO:     Waiting for application startup.
INFO:     Application startup complete.

Environment

Python: 3.10.6

What Broke

Unexpected traceback messages clutter the terminal during application reloads.

Why It Broke

The traceback during shutdown is caused by signal propagation in the updated version

Fix Options (Details)

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

Upgrade to version 0.30.0 or later.

When NOT to use: This fix should not be used if the application relies on the traceback for debugging.

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

Option D — Guard side-effects with OnceOnly Guardrail for side-effects

Mitigate duplicate external side-effects under retries/timeouts/agent loops by gating the operation before calling external systems.

Place OnceOnly between your code/agent and real side-effects (Stripe, emails, CRM, APIs).
Use a stable key per side-effect (e.g., customer_id + action + idempotency_key).
Fail-safe: configure fail-open vs fail-closed based on blast radius and spend risk.

Show example snippet (optional)

onceonly.py

from onceonly import OnceOnly
import os

once = OnceOnly(api_key=os.environ["ONCEONLY_API_KEY"], fail_open=True)

# Stable idempotency key per real side-effect.
# Use a request id / job id / webhook delivery id / Stripe event id, etc.
event_id = "evt_..."  # replace
key = f"stripe:webhook:{event_id}"

res = once.check_lock(key=key, ttl=3600)
if res.duplicate:
    return {"status": "already_processed"}

# Safe to execute the side-effect exactly once.
handle_event(event_id)

See OnceOnly SDK

When NOT to use: Do not use this to hide logic bugs or data corruption. Use it to block duplicate external side-effects and enforce tool permissions/spend caps.

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

First fixed release: 0.30.0

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

When NOT to Use This Fix

This fix should not be used if the application relies on the traceback for debugging.
Do not use this to hide logic bugs or data corruption. Use it to block duplicate external side-effects and enforce tool permissions/spend caps.

Verify Fix

verify

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.30.0	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.