fastapi/fastapi · error · DependencyScopeError

The dependency "{call_name}" has a scope of "request", it ca

Error message

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

What it means

FastAPI computes a dependency scope for each dependency (function or request). A generator dependency (one using yield) that must run for the whole request gets scope 'request'; if such a dependency declares a sub-dependency with scope 'function' (teardown finishes within the function scope), the lifetimes are incompatible and FastAPI raises DependencyScopeError at app setup time: a request-scoped dependency cannot depend on a function-scoped one, because its teardown could outlive the sub-dependency's.

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 a1fa70d423)

Solutions

Give the sub-dependency the wider scope: declare it as a generator with the same/request scope, or pass scope='request' when applicable
Move the function-scoped logic inline into the request-scoped dependency instead of using Depends
Review the dependency scopes documentation and align the tree so scopes never narrow downward
Update FastAPI and fastapi-related dependencies together; older snippets may predate the scope API

Example fix

# before
async def request_scoped_session():
    yield session   # scope 'request'

def read_config(): ...  # scope 'function'

async def dep(cfg = Depends(read_config),   # DependencyScopeError
              s = Depends(request_scoped_session)): ...

# after: make the sub-dependency request-scoped too
async def read_config():
    yield load_config()

async def dep(cfg = Depends(read_config),
              s = Depends(request_scoped_session)): ...

Defensive patterns

Strategy: validation

Validate before calling

from fastapi.dependencies.utils import get_dependant

def verify_scopes(call):
    dep = get_dependant(path='/', call=call)
    # walk sub-dependencies; a request-scoped gen dep must not use
    # function-scoped sub-deps (FastAPI raises DependencyScopeError at setup)
    return dep

# or simply import the app in a startup check: misaligned scopes fail fast
import app  # raises DependencyScopeError at route resolution

Try / catch

try:
    from app.main import app
except Exception as e:
    if 'scope of' in str(e) and 'cannot depend' in str(e):
        fix_dependency_scope(e)  # widen sub-dependency to request scope
    else:
        raise

Prevention

Design dependency trees monotonically: sub-dependency scope >= parent scope
Keep pure config helpers callable without Depends when used by request-scoped sessions
Add an import-the-app smoke test in CI to catch setup-time dependency errors

When it happens

Trigger: A dependency with yield marked or resolved as request-scoped (e.g. via dependencies with scope='request', or the default for yield dependencies under the new scoping rules) whose parameters use Depends() on a plain function or a function-scoped dependency. Raised while building the dependency tree, i.e. at include_router/app startup or first request depending on when routes are resolved.

Common situations: Upgrading FastAPI to a version introducing dependency scopes and mixing old-style sub-dependencies under request-scoped session dependencies; explicitly setting scope='request' on a yield dependency that consumes settings/config functions declared as function-scoped.

Related errors

AI-assisted analysis of fastapi/fastapi@a1fa70d423 (2026-08-14). Data as JSON: /api/errors/f1c23210a3fc9364. Report an issue: GitHub.