uvicorn OSError when --port=0 (Fix)

The Fix

Upgrade to version 0.14.0 or later.

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

@@ -187,7 +187,7 @@ def _log_started_message(self, listeners: List[socket.SocketType]) -> None:
             port = config.port
             if port == 0:
-                port = listeners[0].getpeername()[1]
+                port = listeners[0].getsockname()[1]

repro.py

# example.py
async def app(scope, receive, send):
    assert scope['type'] == 'http'

    await send({
        'type': 'http.response.start',
        'status': 200,
        'headers': [
            [b'content-type', b'text/plain'],
        ],
    })
    await send({
        'type': 'http.response.body',
        'body': b'Hello, world!',
    })

verify

Re-run: venv/linux-3.8/bin/uvicorn example:app --port=0

fix.md

Option A — Upgrade to fixed release\nUpgrade to version 0.14.0 or later.\nWhen NOT to use: This fix should not be applied if the socket handling logic is modified elsewhere.\n\n

Why This Fix Works in Production

Trigger: OSError: [WinError 10057] A request to send or receive data was disallowed because the socket is not connected and (when sending on a datagram socket using a…
Mechanism: The OSError occurs due to a typo in the socket handling logic when using --port=0
Why the fix works: Fixes the OSError encountered when running uvicorn with --port=0 by correcting a typo in the socket handling logic. (first fixed release: 0.14.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.8 in real deployments (not just unit tests).
The OSError occurs due to a typo in the socket handling logic when using --port=0
Surfaces as: OSError: [WinError 10057] A request to send or receive data was disallowed because the socket is not connected and (when sending on a datagram socket using a sendto call) no…

Proof / Evidence

GitHub issue: #974
Fix PR: https://github.com/kludex/uvicorn/pull/975
First fixed release: 0.14.0
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.25

Discussion

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

Jump to Sources Open on GitHub

“correct, seems like a typo from https://github.com/encode/uvicorn/pull/930/files#diff-716652db9a2feab62038753117d5e4fd4294f213f4c7f2edcb47b5788e5209f6L158-R190”

@euri10 · 2021-03-05 · source

Failure Signature (Search String)

OSError: [WinError 10057] A request to send or receive data was disallowed because the socket is not connected and (when sending on a datagram socket using a sendto call) no

Error Message

Stack trace

error.txt

Error Message
-------------
OSError: [WinError 10057] A request to send or receive data was disallowed because the socket is not connected and (when sending on a datagram socket using a sendto call) no address was supplied

Stack trace

error.txt

Error Message
-------------
[12:03:58] D:\sand\uvicorn-port-error
λ venv\win32-3.8\Scripts\uvicorn example:app --port=0
INFO:     Started server process [31268]
INFO:     Waiting for application startup.
INFO:     ASGI 'lifespan' protocol appears unsupported.
INFO:     Application startup complete.
Traceback (most recent call last):
  File "C:\Program Files\Python38\lib\runpy.py", line 194, in _run_module_as_main
    return _run_code(code, main_globals, None,
  File "C:\Program Files\Python38\lib\runpy.py", line 87, in _run_code
    exec(code, run_globals)
  File "D:\sand\uvicorn-port-error\venv\win32-3.8\Scripts\uvicorn.exe\__main__.py", line 7, in <module>
  File "d:\sand\uvicorn-port-error\venv\win32-3.8\lib\site-packages\click\core.py", line 829, in __call__
    return self.main(*args, **kwargs)
  File "d:\sand\uvicorn-port-error\venv\win32-3.8\lib\site-packages\click\core.py", line 782, in main
    rv = self.invoke(ctx)
  File "d:\sand\uvicorn-port-error\venv\win32-3.8\lib\site-packages\click\core.py", line 1066, in invoke
    return ctx.invoke(self.callback, **ctx.params)
  File "d:\sand\uvicorn-port-error\venv\win32-3.8\lib\site-packages\click\core.py", line 610, in invoke
    return callback(*args, **kwargs)
  File "d:\sand\uvicorn-port-error\venv\win32-3.8\lib\site-packages\uvicorn\main.py", line 362, in main
    run(**kwargs)
  File "d:\sand\uvicorn-port-error\venv\win32-3.8\lib\site-packages\uv
... (truncated) ...

Stack trace

error.txt

Error Message
-------------
[12:26:04] /mnt/d/sand/uvicorn-port-error
$ venv/linux-3.8/bin/uvicorn example:app --port=0
INFO:     Started server process [14487]
INFO:     Waiting for application startup.
INFO:     ASGI 'lifespan' protocol appears unsupported.
INFO:     Application startup complete.
Traceback (most recent call last):
  File "venv/linux-3.8/bin/uvicorn", line 8, in <module>
    sys.exit(main())
  File "/mnt/d/sand/uvicorn-port-error/venv/linux-3.8/lib/python3.8/site-packages/click/core.py", line 829, in __call__
    return self.main(*args, **kwargs)
  File "/mnt/d/sand/uvicorn-port-error/venv/linux-3.8/lib/python3.8/site-packages/click/core.py", line 782, in main
    rv = self.invoke(ctx)
  File "/mnt/d/sand/uvicorn-port-error/venv/linux-3.8/lib/python3.8/site-packages/click/core.py", line 1066, in invoke
    return ctx.invoke(self.callback, **ctx.params)
  File "/mnt/d/sand/uvicorn-port-error/venv/linux-3.8/lib/python3.8/site-packages/click/core.py", line 610, in invoke
    return callback(*args, **kwargs)
  File "/mnt/d/sand/uvicorn-port-error/venv/linux-3.8/lib/python3.8/site-packages/uvicorn/main.py", line 362, in main
    run(**kwargs)
  File "/mnt/d/sand/uvicorn-port-error/venv/linux-3.8/lib/python3.8/site-packages/uvicorn/main.py", line 386, in run
    server.run()
  File "/mnt/d/sand/uvicorn-port-error/venv/linux-3.8/lib/python3.8/site-packages/uvicorn/server.py", line 49, in run
..
... (truncated) ...

Minimal Reproduction

repro.py

# example.py
async def app(scope, receive, send):
    assert scope['type'] == 'http'

    await send({
        'type': 'http.response.start',
        'status': 200,
        'headers': [
            [b'content-type', b'text/plain'],
        ],
    })
    await send({
        'type': 'http.response.body',
        'body': b'Hello, world!',
    })

Environment

Python: 3.8

What Broke

Running uvicorn with --port=0 results in an OSError, preventing the server from starting.

Why It Broke

The OSError occurs due to a typo in the socket handling logic when using --port=0

Fix Options (Details)

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

Upgrade to version 0.14.0 or later.

When NOT to use: This fix should not be applied if the socket handling logic is modified elsewhere.

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

First fixed release: 0.14.0

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

When NOT to Use This Fix

This fix should not be applied if the socket handling logic is modified elsewhere.

Verify Fix

verify

Re-run: venv/linux-3.8/bin/uvicorn example:app --port=0

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.

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.

uvicorn OSError when --port=0 (Fix)

The Fix

Why This Fix Works in Production

Why This Breaks in Prod

Proof / Evidence

Discussion

Failure Signature (Search String)

Error Message

Minimal Reproduction

Environment

What Broke

Why It Broke

Fix Options (Details)

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

Get updates

When NOT to Use This Fix

Verify Fix

Did This Fix Work in Your Case?

Prevention

Version Compatibility Table

Related Issues

Sources