explicitly start ASGI run with empty context by pmeier · Pull Request #2742 · Kludex/uvicorn

pmeier · 2025-10-29T15:29:37Z

Summary

One possible solution for #2167.

Checklist

I understand that this PR may be closed in case there was no previous discussion. (This doesn't apply to typos!)
I've added a test for each change that was introduced, and I tried as much as possible to make a single atomic change.
I've updated the documentation accordingly.

Kludex · 2025-10-29T15:52:11Z

This does make sense, but do you know why it happens?

pmeier · 2025-10-29T19:55:25Z

~~I think so, yes. asyncio does not clean up the context when starting a new task. This is why they added the context keyword argument in 3.11 to make this simpler. The documentation states~~

~~> The current context copy is created when no context is provided.~~

~~So far I only have a not-so-minimal reproducer: https://github.com/pmeier/asyncio-contextvars-pollution. Using the patch in this PR, the pollution is resolved.~~

How exactly it happens in the first place, I don't know yet. My goal is to get to a reproducer that just depends on uvicorn that I hopefully can put into a unittest. This could serve as testing ground to find the underlying reason.

Finally, my working hypothesis as for why this is not happening by uvloop is that they are not a drop-in replacement for this specific behavior of asyncio. On the surface it seems that they are replicating it correctly, but I haven't dug any deeper just yet.

@Kludex I was wrong. This is a bug in asyncio. See #2167 (comment) for details.

pmeier · 2025-11-16T10:42:51Z

Ping @Kludex

Kludex · 2025-11-17T10:01:25Z

We need to fix it in httptools as well, and do you think you can create a test that reproduces the issue?

pmeier · 2025-11-17T17:00:23Z

@Kludex

We need to fix it in httptools as well

Can you explain that? Are you talking about

uvicorn/pyproject.toml

Lines 41 to 44 in 8ae0bcb

    
           [project.optional-dependencies] 
        
           standard = [ 
        
               "colorama>=0.4; sys_platform == 'win32'", 
        
               "httptools>=0.6.3",

https://github.com/MagicStack/httptools

do you think you can create a test that reproduces the issue?

Yeah, likely. I haven't written one, because the solution is not the only one that is possible to fix the issue. See #2167 (comment).

Can you decide if you want to go with the solution before I put in more work?

Kludex · 2025-11-21T09:38:56Z

Can you decide if you want to go with the solution before I put in more work?

It's a bit unfortunate we need to do it here, but I guess it's fine.

Can you explain that? Are you talking about

We have a h11_impl.py and httptools_impl.py that has analogous logic.

…o reset-context

pmeier · 2025-11-21T13:40:44Z

@Kludex

It's a bit unfortunate we need to do it here, but I guess it's fine.

There is an open PR python/cpython#141158 that'll hopefully fix this for Python >=3.15. But until that there is no way around doing this in uvicorn if we don't want to tell users to use uvloop by default.

can create a test that reproduces the issue

I've added a test that should reproduce the issue. However, it also won't pass right now I don't know why yet. Trying my fix on reproducers outside of the test suite works just fine. Thus, my working assumption is that one of the mock components does not behave like the real component would. I'll try to find out which one.

pmeier

@Kludex I opted to avoid using the mock components, because in order to reproduce the issue, we'd need to implement the buggy behavior for them. Instead, the regression test now uses the outer asyncio loop.

The CI for d099a87 (just the test without the changes to the task handling) shows nicely that

The regression test correctly fails if we do not start the ASGI task with an empty context
Windows is not affected by this bug (see #2167 (comment))

pmeier · 2025-11-24T13:41:19Z

+
+
+@contextlib.asynccontextmanager
+async def server(*, app, port, http_protocol_cls):


Naming TBD. Just wanted to get feedback first if the test architecture is ok.

You should use run_server from utils.py.

This reverts commit d099a87.

pmeier · 2025-12-08T14:33:44Z

Ping @Kludex

Kludex · 2025-12-17T09:04:07Z

+                # For the asyncio loop, we need to explicitly start with an empty context
+                # as it can be polluted from previous ASGI runs.
+                # See https://github.com/python/cpython/issues/140947 for details.
+                task = contextvars.Context().run(self.loop.create_task, self.cycle.run_asgi(app))
+                # TODO: Replace the line above with the line below for Python >= 3.11
+                # task = self.loop.create_task(self.cycle.run_asgi(app), context=contextvars.Context())


Currently, the lifespan is a sibling task, but that's not the case in Hypercorn. It may be the case in the future that we refactor the server to make the lifespan task a parent of the whole process instead of a sibling task. Which means that the context would need to come from there. We still don't want the context to leak between sibling tasks as it's currently happening in asyncio...

Since this is going to be fixed in Python 3.15, can we have a note about it? I would like to revert the context= when it lands, or at least remember that we can do it if we decide to make the lifespan task a parent from this one.

I'm aware of python/cpython#141158, but since this is not merged or ready to be merged, do we already want to assume that 3.15 will fix this?

Kludex · 2025-12-17T09:04:24Z

+        await task
+
+
+async def test_no_contextvars_pollution(http_protocol_cls: type[HTTPProtocol], unused_tcp_port: int):


Suggested change

async def test_no_contextvars_pollution(http_protocol_cls: type[HTTPProtocol], unused_tcp_port: int):

async def test_no_contextvars_pollution_asyncio(http_protocol_cls: type[HTTPProtocol], unused_tcp_port: int):

Kludex · 2025-12-17T09:04:50Z

+
+
+@contextlib.asynccontextmanager
+async def server(*, app, port, http_protocol_cls):


Suggested change

async def server(*, app, port, http_protocol_cls):

async def server(*, app: ASGIApplication, port: int, http_protocol_cls: type[HTTPProtocol]):

Kludex · 2025-12-17T09:11:54Z

+        await task
+
+
+async def test_no_contextvars_pollution(http_protocol_cls: type[HTTPProtocol], unused_tcp_port: int):


I would like to remove this test when 3.15 reaches EOF, given it's the event loop's job to make sure this is the case. 😎

Can we have a mark to not run this on >=3.15? 🙏

We can depending on the answer of #2742 (comment).

Kludex · 2025-12-17T09:12:16Z

Ping @Kludex

Sorry. I was on a short vacation.

marctc · 2026-01-22T09:48:46Z

hey @Kludex @pmeier I dont have much expertise on asyncio stuff, but is this a temporary fix or the path this project will go? I'm asking because I'm working on implementing automatic context propagation for python asyncio with eBPF and I found out that this PR breaks the use case of FasAPI+uvicorn. The conflicting bit is where "we need to explicitly start with an empty context". We are using eBPF to track the execution of context_run and context_create from CPython to create connected spans for a distributed trace and from version 0.39 of uvicorn tests are failing.

thanks!

pmeier · 2026-01-22T10:01:40Z

is this a temporary fix or the path this project will go

I can't answer for the project / @Kludex, but IMO this is just a temporary fix. This is only required, because asyncio is leaking context vars out of tasks.

I'm interested in your use case though: are you setting a "global" context var, i.e. not on a per-request basis, and by starting with an empty context this global context is hidden?

marctc · 2026-01-22T10:23:30Z

Hey @pmeier thanks for quick response!

I'm interested in your use case though: are you setting a "global" context var, i.e. not on a per-request basis, and by starting with an empty context this global context is hidden?

We hook context_run (which is called when Context.run() executes) and context_new_from_vars (when a new context is created). When a request comes in, we capture the Python context pointer and store it in a BPF map, associating it with the trace. When that same request makes an outgoing HTTP call, we look up the current context pointer to find the parent trace and link the spans together.

Before 0.39, this worked because the request handler inherited whatever context was active. The context pointer we captured at request start was the same one (or a child of it) when the handler made HTTP calls.
After 0.39, with contextvars.Context().run(...), each request gets a brand new empty context. So the context pointer we see inside the request handler has no relationship to anything we tracked before - it's a fresh object created just for that request. We can't follow the parent chain because there isn't one.

So we're not setting a "global" contextvar. Instead, we intercept the C functions in libpython that manage context objects and track the raw memory addresses (pointers) of those PyContext objects.

Kludex · 2026-01-22T10:50:39Z

I think we should make lifespan a parent task, and then use the context from there.

We can also make this fix only for asyncio, and leave uvloop out of it, since it's what people will use in production.

marctc · 2026-01-22T12:13:46Z

Hey thanks also for quick response!

We can also make this fix only for asyncio, and leave uvloop out of it, since it's what people will use in production.

Unless I'm doing something wrong or I missunderstood your message, it's also broken for uvicorn + uvloop. I never tested with uvloop before and I had to tweak the code, but it works for versions prior 0.39.

Kludex · 2026-01-22T12:16:29Z

Hey thanks also for quick response!

We can also make this fix only for asyncio, and leave uvloop out of it, since it's what people will use in production.

Unless I'm doing something wrong or I missunderstood your message, it's also broken for uvicorn + uvloop. I never tested with uvloop before and I had to tweak the code, but it works for versions prior 0.39.

What I meant is to "revert" this PR for uvloop, since the problem this PR tried to solve was not an issue with uvloop.

Kludex · 2026-01-22T12:17:11Z

By "revert" here I mean wrap the line that runs the app, check what event loop is running, and apply a behavior accordingly.

marctc · 2026-01-22T12:30:26Z

I see, I understand now, thanks for clarifying!

This reverts commit d94bf28.

Co-authored-by: Marcelo Trylesinski <marcelotryle@gmail.com>

tubarao312 · 2026-04-03T17:48:03Z

Hi, this fix has actually broken some metaprogramming features I was relying on - I was accessing a single variable for multiple uvicorn apps in my monorepo and then changing the variable depending on the context it was in. This context is no longer accessible inside ASGI function calls. Any idea what I should do?

Pinging @Kludex since this is a rather old thread.

Also I realize this might seem like an insane use of context vars but from my point of view it made a lot of sense that I could use a FastAPI lifespan to inject whatever I wanted into the context. Classic Hyrum's Law 😅:

With a sufficient number of users of an API, it does not matter what you promise in the contract: all observable behaviours of your system will be depended on by somebody.

Kludex · 2026-04-03T17:54:41Z

@pmeier I know it's just one user complaining (for now), but I think it's a fair point. I'm inclined to revert the changes (given that I've seen progress on the CPython side for 3.15).

[...] seem like an insane use of context vars

It does, but my reasoning was that the current bug in CPython (and the non-predictability behavior) overweights that.

pmeier · 2026-04-10T20:37:31Z

Yeah, I get it. TBH when I started this I was 90%+ sure that this was a bug in uvicorn rather than CPython. And after I was finally able to reproduce it with just CPython, I just wanted "closure".

But I guess your reasoning to revert is sound. We just need to make sure to also push this to downstream projects. For example, I originally stumbled over this bug when instrumenting with opentelemetry. And after my fix here was merged and released, I posted there that the bug reports can be closed: open-telemetry/opentelemetry-python-contrib#2852 (comment)

Reintroduces the behavior from #2742 as an opt-in flag. When set, each ASGI request runs in a fresh contextvars.Context, which works around the asyncio context leak in python/cpython#140947 (expected to be fixed upstream for Python >=3.15 via python/cpython#141158). Default is off so context set in the lifespan or by external instrumentation (e.g. OpenTelemetry eBPF propagation) remains visible to ASGI handlers.

Kludex · 2026-04-21T09:47:28Z

I've reverted this PR and merged #2912.

To have this behavior, you need to opt-in with --reset-contextvars.

I'm sorry for the delay. I'll post a message on related closed issues.

explicitly start with empty context

b809956

pmeier mentioned this pull request Nov 3, 2025

ContextVars pollution when uvicorn installed without [standard] extensions #2167

Closed

expand comment

31d6abc

pmeier marked this pull request as ready for review November 3, 2025 15:10

Merge branch 'main' into reset-context

a631e4d

pmeier changed the title ~~explicitly start with empty context~~ explicitly start ASGI run with empty context Nov 3, 2025

Merge branch 'main' into reset-context

aa2e04a

pmeier added 5 commits November 21, 2025 11:17

add fix to httptools

e6da183

add test

6036a1f

Merge branch 'main' into reset-context

7c24f4a

Merge branch 'reset-context' of https://github.com/pmeier/uvicorn int…

e85a86d

…o reset-context

test cleanup

0cf9b38

pmeier added 2 commits November 24, 2025 14:31

fix test

7e2f7b9

[REVERTME] test regression

d099a87

pmeier commented Nov 24, 2025

View reviewed changes

Revert "[REVERTME] test regression"

3d6a256

This reverts commit d099a87.

Kludex reviewed Dec 17, 2025

View reviewed changes

fix my stuff

3a28019

Kludex merged commit d94bf28 into Kludex:main Dec 21, 2025
40 of 44 checks passed

This was referenced Dec 23, 2025

Test CI stability PrefectHQ/fastmcp#2684

Closed

Fix test cleanup for uvicorn 0.39+ context isolation PrefectHQ/fastmcp#2696

Merged

Fix uvicorn 0.39+ test timeouts and FastMCPError propagation PrefectHQ/fastmcp#2699

Merged

hingebase mentioned this pull request Jan 10, 2026

Incompatibility with Uvicorn >=0.39.0 hingebase/mahoraga#53

Closed

Kludex added a commit that referenced this pull request Jan 30, 2026

Revert "explicitly start ASGI run with empty context (#2742)"

c7e22ce

This reverts commit d94bf28.

marctc mentioned this pull request Feb 11, 2026

Support python asyncio context propagation open-telemetry/opentelemetry-ebpf-instrumentation#1198

Open

3 tasks

theseriff pushed a commit to theseriff/uvicorn that referenced this pull request Mar 9, 2026

explicitly start ASGI run with empty context (Kludex#2742)

754be10

Co-authored-by: Marcelo Trylesinski <marcelotryle@gmail.com>

pmeier deleted the reset-context branch April 10, 2026 20:37

flowjzh mentioned this pull request Apr 21, 2026

fix: restore context vars in resolve_tool endpoint emcie-co/parlant#781

Merged

Kludex mentioned this pull request Apr 21, 2026

Revert empty context for ASGI runs #2911

Merged

4 tasks

Kludex mentioned this pull request Apr 21, 2026

Add --reset-contextvars flag to isolate ASGI request context #2912

Merged

6 tasks



		@contextlib.asynccontextmanager
		async def server(*, app, port, http_protocol_cls):

		await task


		async def test_no_contextvars_pollution(http_protocol_cls: type[HTTPProtocol], unused_tcp_port: int):

	async def test_no_contextvars_pollution(http_protocol_cls: type[HTTPProtocol], unused_tcp_port: int):
	async def test_no_contextvars_pollution_asyncio(http_protocol_cls: type[HTTPProtocol], unused_tcp_port: int):

	async def server(*, app, port, http_protocol_cls):
	async def server(*, app: ASGIApplication, port: int, http_protocol_cls: type[HTTPProtocol]):

Uh oh!

Conversation

pmeier commented Oct 29, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Summary

Checklist

Uh oh!

Kludex commented Oct 29, 2025

Uh oh!

pmeier commented Oct 29, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

pmeier commented Nov 16, 2025

Uh oh!

Kludex commented Nov 17, 2025

Uh oh!

pmeier commented Nov 17, 2025

Uh oh!

Kludex commented Nov 21, 2025

Uh oh!

pmeier commented Nov 21, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

pmeier left a comment

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

pmeier commented Dec 8, 2025

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Kludex commented Dec 17, 2025

Uh oh!

Uh oh!

marctc commented Jan 22, 2026

Uh oh!

pmeier commented Jan 22, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

marctc commented Jan 22, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

Kludex commented Jan 22, 2026

Uh oh!

marctc commented Jan 22, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

Kludex commented Jan 22, 2026

Uh oh!

Kludex commented Jan 22, 2026

Uh oh!

marctc commented Jan 22, 2026

Uh oh!

tubarao312 commented Apr 3, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

Kludex commented Apr 3, 2026

Uh oh!

pmeier commented Apr 10, 2026

Uh oh!

Kludex commented Apr 21, 2026

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

pmeier commented Oct 29, 2025 •

edited

Loading

pmeier commented Oct 29, 2025 •

edited

Loading

pmeier commented Nov 21, 2025 •

edited

Loading

pmeier commented Jan 22, 2026 •

edited

Loading

marctc commented Jan 22, 2026 •

edited

Loading

marctc commented Jan 22, 2026 •

edited

Loading

tubarao312 commented Apr 3, 2026 •

edited

Loading