tiangolo/fastapi · error · DependencyScopeError

The dependency " " has a scope of "request", it cannot…

Error message

The dependency "{call_name}" has a scope of "request", it cannot depend on dependencies with scope "function".

What it means

DependencyScopeError (a FastAPIError/RuntimeError) raised while building the dependency tree in get_dependant. It fires when a dependency whose computed scope is "request" (typically a generator/async-generator dependency, or one declared with Depends(scope="request")) lists a sub-dependency explicitly scoped to "function". A request-scoped dependency outlives the per-function teardown, so depending on something that is torn down at function scope would close resources too early; FastAPI forbids the combination at app construction.

Solutions

Make the sub-dependency request-scoped too: Depends(get_thing, scope="request"), so scopes are compatible.
Or remove the explicit scope from the parent so its computed scope becomes "function".
Reorder so the function-scoped dependency is injected at the endpoint level, not under the request-scoped one.
Audit all Depends(...) calls in the chain and align their scope= values.

Example fix

# before
def get_auth(token: str = Depends(oauth2)) -> User: ...  # scope="function" (default)

def get_db(db=Depends(get_auth, scope="request")):  # request depends on function
    yield db
# -> DependencyScopeError

# after
def get_auth(token: str = Depends(oauth2, scope="request")) -> User: ...

def get_db(db=Depends(get_auth, scope="request")):
    yield db

Defensive patterns

Strategy: validation

Validate before calling

# Walk your dependency graph at startup and reject invalid scope mixes
from fastapi import Depends

def get_depends_chain(func):
    import inspect
    deps = []
    for p in inspect.signature(func).parameters.values():
        if isinstance(p.default, Depends):
            deps.append((p.name, getattr(p.default, "scope", None)))
    return deps

# rule: a request-scoped parent must not depend on a function-scoped child
for parent_name, parent_scope in get_depends_chain(my_endpoint):
    assert parent_scope != "request" or not has_function_scope_child(parent_name), (
        f"{parent_name} is request-scoped but depends on a function-scoped dep"
    )

Try / catch

from fastapi.exceptions import DependencyScopeError
try:
    app.include_router(router)  # dependency tree is built here
except DependencyScopeError as e:
    print("scope mismatch in dependency tree:", e)
    raise

Prevention

Keep dependency scopes consistent across a chain (all request or all function).
Avoid mixing Depends(..., scope=...) values without auditing the whole subtree.
Inject function-scoped deps at the endpoint, not under a request-scoped parent.
Add a startup test that imports the app to catch scope errors in CI.

When it happens

Trigger: Declaring a yielding dependency at request scope (e.g. Depends(get_db, scope="request") where get_db is a generator) and having it depend on another Depends(..., scope="function"). The check at dependencies/utils.py:304-317 raises when _get_computed_scope(dependant) == "request" and param_details.depends.scope == "function".

Common situations: Mixing FastAPI dependency scopes (newer scope= feature); a request-scoped DB session dependency that Depends on a function-scoped settings/auth dependency; upgrading to a FastAPI version that enforces scope rules on previously-loose code.

Related errors

AI-assisted analysis of tiangolo/fastapi@3e8d1526d8 (2026-08-11). Data as JSON: /api/errors/34ae2121b11055fb. Report an issue: GitHub.

Appendix: source

Thrown at fastapi/dependencies/utils.py:314

        param_details = analyze_param(
            param_name=param_name,
            annotation=param.annotation,
            value=param.default,
            is_path_param=is_path_param,
        )
        if param_details.depends is not None:
            assert param_details.depends.dependency
            if (
                (
                    _is_gen_callable(dependant.call)
                    or _is_async_gen_callable(dependant.call)
                )
                and _get_computed_scope(dependant=dependant) == "request"
                and param_details.depends.scope == "function"
            ):
                assert dependant.call
                call_name = getattr(dependant.call, "__name__", "<unnamed_callable>")
                raise DependencyScopeError(
                    f'The dependency "{call_name}" has a scope of '
                    '"request", it cannot depend on dependencies with scope "function".'
                )
            sub_own_oauth_scopes: list[str] = []
            if isinstance(param_details.depends, params.Security):
                if param_details.depends.scopes:
                    sub_own_oauth_scopes = list(param_details.depends.scopes)
            sub_dependant = get_dependant(
                path=path,
                call=param_details.depends.dependency,
                name=param_name,
                own_oauth_scopes=sub_own_oauth_scopes,
                parent_oauth_scopes=current_scopes,
                use_cache=param_details.depends.use_cache,
                scope=param_details.depends.scope,
            )
            dependant.dependencies.append(sub_dependant)
            continue

View on GitHub (pinned to 3e8d1526d8)