Non-admin users on DeepTutor were getting 404 on every session request. Admins were fine. The 404 was coming from a permission check that read the current user out of a ContextVar, found None, and refused the request. The auth dependency had run, and the auth dependency had called current_user.set(user) with a real user before returning. The value never reached the endpoint.

The fix was a one-keyword change: turn the dependency from def into async def. To understand why that fixes it I had to read the framework's dispatcher.

The trace

The dependency looked like this:

def require_auth(token: str = Depends(oauth2_scheme)) -> User:
    user = verify_token(token)
    current_user.set(user)
    return user

And the endpoint, simplified, like this:

@router.get("/sessions/{sid}")
async def get_session(sid: str, user: User = Depends(require_auth)):
    if not has_permission(sid, current_user.get()):
        raise HTTPException(404)
    ...

The endpoint received user as a parameter and used it correctly when accessed that way. The bug was inside has_permission, which read from current_user rather than taking the user as an argument. current_user.get() returned the default. has_permission returned False. The endpoint raised 404.

Two-hour stretch of wrong hypotheses. First I assumed the ContextVar default was set wrong. It was not; the default was None intentionally. Then I assumed the dependency was being short-circuited by FastAPI's cache, never actually running for non-admin users. I added a log line at the top of require_auth; it printed. Then I assumed current_user was being reassigned to a fresh module between the dependency and the endpoint. It was not; id(current_user) was identical in both. Then I added print(current_user.get()) immediately after the set and immediately at the top of the endpoint. The first print showed the user. The second showed None. The dependency's write was real; the endpoint's read was real; they were happening in different contexts.

Once that was the symptom, the cause became findable. I went into FastAPI source.

Why the write disappears

FastAPI's solve_dependencies looks at each dependency. If the callable is async, it awaits it directly in the same task. If the callable is sync, it dispatches it through anyio.to_thread.run_sync. That second path is the trap.

anyio.to_thread.run_sync exists to keep a sync function from blocking the event loop. It runs the sync callable in a worker thread. To preserve correctness across the boundary it captures the current Python context with contextvars.copy_context() and runs the sync callable under that copy.

The relevant sentence is in the contextvars docs: "Any changes to the Context object are local to the Context. The next time Context.run is called, it will work with the new Context." A ContextVar.set performed inside a context copy is invisible to anything outside that copy. The sync dependency wrote to the copy. The endpoint ran in the original context, which had no such write.

The fix is to remove the boundary. An async def dependency runs in the same task as the endpoint, in the same context, and a ContextVar.set there is visible to the endpoint exactly as a programmer would expect. The verify_token call I needed to make was already non-blocking; the sync def had been a habit, not a requirement.

async def require_auth(token: str = Depends(oauth2_scheme)) -> User:
    user = await verify_token(token)
    current_user.set(user)
    return user

Non-admin users started getting their sessions back.

The shape of the bug, generalized

Three things have to line up for this to bite you, and once they do, it's stubbornly invisible.

One. The framework dispatches some handlers through a context-copying boundary. FastAPI does this for sync deps. Django does it through ASGI middleware in some configurations. Many job-queue libraries do it for task workers. Anything that uses anyio.to_thread.run_sync, asyncio.to_thread, or concurrent.futures with explicit contextvars.copy_context falls into the same shape.

Two. The handler that crosses the boundary mutates a ContextVar with the intent that downstream code in the same logical request will see the mutation.

Three. The downstream code reads the ContextVar directly rather than receiving the value as a parameter. The parameter path works fine because the value is passed by reference through normal function calls. The ContextVar path is what the boundary erases.

When all three are true, the symptom is the one I saw: the write looks correct, the read looks correct, neither logs anything wrong, and the value is gone in between. The mechanism is invisible at the call site. You have to read the dispatcher.

What I'd do differently

The two hours of wrong hypotheses were spent at the call site. The right move, on hour one rather than hour two, was to ask the framework's source what happens between dependency return and endpoint entry. solve_dependencies in FastAPI is about three hundred lines; the relevant branch is a single if iscoroutinefunction check. Reading those three hundred lines would have taken twenty minutes and shown me the run_in_threadpool call directly.

The general rule I'm pulling out: when context disappears across a function boundary in a framework, read the dispatcher. The call site is rarely lying. The boundary is.

The same shape applies any time a value crosses an executor, a worker pool, or a copy-context. Logging at the boundary is more useful than logging at the call site. id(current_context()) at the dependency exit and at the endpoint entry would have caught this in five minutes.

Takeaway

If your sync FastAPI dependency sets a ContextVar and the endpoint reads the default, the dependency is running under a context copy and your write is being thrown away. Make the dependency async def. The fix is one keyword. The mechanic is worth knowing because every framework that crosses a thread boundary or a context copy can produce the same symptom with the same invisibility.

The fix landed as HKUDS/DeepTutor#485. Sources: FastAPI's fastapi/dependencies/utils.py (solve_dependencies and run_in_threadpool), anyio's to_thread.run_sync docs, Python's contextvars.copy_context documentation.