uvicorn Invalid argument was supplied error on windows (Fix)

The Fix

Upgrade to version 0.12.2 or later.

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

@@ -414,8 +414,19 @@ async def startup(self, sockets=None):
             # Explicitly passed a list of open sockets.
             # We use this when the server is run from a Gunicorn worker.
+
+            def _share_socket(sock: socket) -> socket:
+                # Windows requires the socket be explicitly shared across

repro.py

INFO:     Uvicorn running on http://127.0.0.1:9000 (Press CTRL+C to quit)
INFO:     Started parent process [17696]
INFO:     Started server process [20428]
INFO:     Started server process [15476]
INFO:     Waiting for application startup.
INFO:     Waiting for application startup.
INFO:     ASGI 'lifespan' protocol appears unsupported.
INFO:     ASGI 'lifespan' protocol appears unsupported.
INFO:     Application startup complete.
INFO:     Application startup complete.
Process SpawnProcess-2:
Traceback (most recent call last):
  File "c:\users\arnab\appdata\local\programs\python\python37-32\Lib\multiprocessing\process.py", line 297, in _bootstrap    
    self.run()
  File "c:\users\arnab\appdata\local\programs\python\python37-32\Lib\multiprocessing\process.py", line 99, in run
    self._target(*self._args, **self._kwargs)
  File "t:\my projects\scholify-web\env\lib\site-packages\uvicorn\subprocess.py", line 62, in subprocess_started
    target(sockets=sockets)
  File "t:\my projects\scholify-web\env\lib\site-packages\uvicorn\main.py", line 382, in run
    loop.run_until_complete(self.serve(sockets=sockets))
  File "c:\users\arnab\appdata\local\programs\python\python37-32\Lib\asyncio\base_events.py", line 579, in run_until_complete
    return future.result()
  File "t:\my projects\scholify-web\env\lib\site-packages\uvicorn\main.py", line 399, in serve
    await self.startup(sockets=sockets)
  File "t:\my projects\scholify-web\env\lib\site-packages\uvicorn\main.py", line 433, in startup
    create_protocol, sock=sock, ssl=config.ssl, backlog=config.backlog
  File "c:\users\arnab\appdata\local\programs\python\python37-32\Lib\asyncio\base_events.py", line 1393, in create_server    
    server._start_serving()
  File "c:\users\arnab\appdata\local\programs\python\python37-32\Lib\asyncio\base_events.py", line 282, in _start_serving    
    sock.listen(self._backlog)
OSError: [WinError 10022] An invalid argument was supplied

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.12.2 or later.\nWhen NOT to use: Do not use this fix if running on non-Windows platforms or with a single worker.\n\n

Why This Fix Works in Production

Trigger: Process SpawnProcess-2:
Mechanism: The error occurs due to improper socket sharing across multiple worker processes on Windows
Why the fix works: Fixes the invalid argument error on Windows when using multiple workers in Uvicorn. (first fixed release: 0.12.2).

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 error occurs due to improper socket sharing across multiple worker processes on Windows
Surfaces as: INFO: Uvicorn running on http://127.0.0.1:9000 (Press CTRL+C to quit)

Proof / Evidence

GitHub issue: #683
Fix PR: https://github.com/kludex/uvicorn/pull/802
First fixed release: 0.12.2
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.27

Discussion

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

Jump to Sources Open on GitHub

“this one has a fix I really dont understand”

@euri10 · 2020-09-29 · source

“I get the same error when use multiple workers on win11(22H2) and uvicorn 0.22.0. It seems the error only appears when use workers=2”

@qqletter · 2023-06-06 · source

“Please check the current open issues instead of commenting on a 3 years old issue that was solved.”

@Kludex · 2023-06-06 · source

Failure Signature (Search String)

Process SpawnProcess-2:

Error Message

Stack trace

error.txt

Error Message
-------------
INFO:     Uvicorn running on http://127.0.0.1:9000 (Press CTRL+C to quit)
INFO:     Started parent process [17696]
INFO:     Started server process [20428]
INFO:     Started server process [15476]
INFO:     Waiting for application startup.
INFO:     Waiting for application startup.
INFO:     ASGI 'lifespan' protocol appears unsupported.
INFO:     ASGI 'lifespan' protocol appears unsupported.
INFO:     Application startup complete.
INFO:     Application startup complete.
Process SpawnProcess-2:
Traceback (most recent call last):
  File "c:\users\arnab\appdata\local\programs\python\python37-32\Lib\multiprocessing\process.py", line 297, in _bootstrap    
    self.run()
  File "c:\users\arnab\appdata\local\programs\python\python37-32\Lib\multiprocessing\process.py", line 99, in run
    self._target(*self._args, **self._kwargs)
  File "t:\my projects\scholify-web\env\lib\site-packages\uvicorn\subprocess.py", line 62, in subprocess_started
    target(sockets=sockets)
  File "t:\my projects\scholify-web\env\lib\site-packages\uvicorn\main.py", line 382, in run
    loop.run_until_complete(self.serve(sockets=sockets))
  File "c:\users\arnab\appdata\local\programs\python\python37-32\Lib\asyncio\base_events.py", line 579, in run_until_complete
    return future.result()
  File "t:\my projects\scholify-web\env\lib\site-packages\uvicorn\main.py", line 399, in serve
    await self.startup(soc
... (truncated) ...

Minimal Reproduction

repro.py

INFO:     Uvicorn running on http://127.0.0.1:9000 (Press CTRL+C to quit)
INFO:     Started parent process [17696]
INFO:     Started server process [20428]
INFO:     Started server process [15476]
INFO:     Waiting for application startup.
INFO:     Waiting for application startup.
INFO:     ASGI 'lifespan' protocol appears unsupported.
INFO:     ASGI 'lifespan' protocol appears unsupported.
INFO:     Application startup complete.
INFO:     Application startup complete.
Process SpawnProcess-2:
Traceback (most recent call last):
  File "c:\users\arnab\appdata\local\programs\python\python37-32\Lib\multiprocessing\process.py", line 297, in _bootstrap    
    self.run()
  File "c:\users\arnab\appdata\local\programs\python\python37-32\Lib\multiprocessing\process.py", line 99, in run
    self._target(*self._args, **self._kwargs)
  File "t:\my projects\scholify-web\env\lib\site-packages\uvicorn\subprocess.py", line 62, in subprocess_started
    target(sockets=sockets)
  File "t:\my projects\scholify-web\env\lib\site-packages\uvicorn\main.py", line 382, in run
    loop.run_until_complete(self.serve(sockets=sockets))
  File "c:\users\arnab\appdata\local\programs\python\python37-32\Lib\asyncio\base_events.py", line 579, in run_until_complete
    return future.result()
  File "t:\my projects\scholify-web\env\lib\site-packages\uvicorn\main.py", line 399, in serve
    await self.startup(sockets=sockets)
  File "t:\my projects\scholify-web\env\lib\site-packages\uvicorn\main.py", line 433, in startup
    create_protocol, sock=sock, ssl=config.ssl, backlog=config.backlog
  File "c:\users\arnab\appdata\local\programs\python\python37-32\Lib\asyncio\base_events.py", line 1393, in create_server    
    server._start_serving()
  File "c:\users\arnab\appdata\local\programs\python\python37-32\Lib\asyncio\base_events.py", line 282, in _start_serving    
    sock.listen(self._backlog)
OSError: [WinError 10022] An invalid argument was supplied

What Broke

The application fails to start with an OSError when using multiple workers.

Why It Broke

The error occurs due to improper socket sharing across multiple worker processes on Windows

Fix Options (Details)

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

Upgrade to version 0.12.2 or later.

When NOT to use: Do not use this fix if running on non-Windows platforms or with a single worker.

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/802

First fixed release: 0.12.2

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

When NOT to Use This Fix

Do not use this fix if running on non-Windows platforms or with a single worker.

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

Add a TLS smoke test that performs a real handshake in CI (include CA bundle validation and hostname checks).
Alert on handshake failures by error string and endpoint to catch cert/CA changes quickly.

Version Compatibility Table

Version	Status
0.12.2	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.