PrefectHQ/fastmcp · error · RuntimeError

Failed to resolve dependency '{parameter}' for {fn_name}

Error message

Failed to resolve dependency '{parameter}' for {fn_name}

What it means

FastMCP resolves function parameters marked as dependencies (e.g. Context, Progress, AccessToken providers) before invoking a tool, resource, or prompt. When a dependency's factory raises any exception other than a dependency CycleError (which is re-raised verbatim so the cycle path stays visible), it is wrapped in a RuntimeError naming the parameter and the function, with the original error attached via `raise ... from error`. The wrapper exists to tell you exactly which parameter on which function could not be resolved.

Source

Thrown at fastmcp_slim/fastmcp/server/dependencies.py:813

                # the same value the function receives for it.
                with frame_scope(fn, arguments) as frame:
                    resolved: dict[str, Any] = {}

                    for parameter in dependency_params:
                        # Resolve the dependency. The frame returns an
                        # explicitly provided argument as-is.
                        try:
                            resolved[parameter] = await frame.resolve(parameter)
                        except (FastMCPError, CycleError):
                            # Let FastMCPError subclasses (ToolError,
                            # ResourceError, etc.) propagate unchanged so they
                            # can be handled appropriately. CycleError already
                            # names the cyclic reference path, so wrapping it
                            # would only hide that.
                            raise
                        except Exception as error:
                            fn_name = getattr(fn, "__name__", repr(fn))
                            raise RuntimeError(
                                f"Failed to resolve dependency '{parameter}' "
                                f"for {fn_name}"
                            ) from error

                    # Merge resolved dependencies with provided arguments
                    final_arguments = {**arguments, **resolved}

                    yield final_arguments
            finally:
                _Depends.stack.reset(stack_token)
    finally:
        _Depends.cache.reset(cache_token)


@asynccontextmanager
async def resolve_dependencies(
    fn: Callable[..., Any], arguments: dict[str, Any]
) -> AsyncGenerator[dict[str, Any], None]:

View on GitHub (pinned to 1f02114297)

Solutions

1. Read the chained `from error` cause in the traceback (the `__cause__`) — the RuntimeError only names the parameter; the real failure is the inner exception
2. Check the annotated type of the named parameter on fn_name; ensure it maps to a registered dependency provider
3. If the parameter needs a request context (Context/Progress/AccessToken), only invoke the function through the FastMCP server request path, not directly in a background thread
4. If it is a custom dependency, fix the exception raised inside its factory/__aenter__

Example fix

// before
def my_tool(progress: Progress, db: NotADependency) -> str: ...
// after
from fastmcp.server.dependencies import Progress
def my_tool(ctx: Context, progress: Progress) -> str: ...

import inspect, fastmcp.server.dependencies as deps
for name, ann in inspect.signature(fn).parameters.items():
    if ann.annotation in deps._known_dependency_types():
        print(f'{name} resolves via built-in provider')

def has_dependency_params(fn) -> bool:
    return any(
        isinstance(p.annotation, type) and issubclass(p.annotation, Dependent)
        for p in inspect.signature(fn).parameters.values()
    )

try:
    args = resolve_dependencies(fn, arguments)
except RuntimeError as e:
    logger.error(f'{e.__cause__!r}')  # real cause is chained
    raise

When it happens

Trigger: Calling resolve_dependencies on a function whose annotated dependency parameter raises during resolution — e.g. a Progress or AccessToken provider entered outside a server context, a user-supplied dependency factory raising, or a type annotation that maps to no known provider and its factory throws.

Common situations: A tool with a `progress: Progress` parameter invoked via the client (not inside a request context); a custom dependency class whose __aenter__ raises; renaming a function so an internal registry lookup fails; typos in dependency type annotations.

Related errors

• mcp_tool() got unexpected keyword argument(s): {sorted(unkno
• mcp_resource() got unexpected keyword argument(s): {sorted(u
• mcp_prompt() got unexpected keyword argument(s): {sorted(unk
• {name!r} moved to the fastmcp-tasks package. Install it with
• module {__name__!r} has no attribute {name!r}

AI-assisted analysis of PrefectHQ/fastmcp@1f02114297 (2026-08-29). Data as JSON: /api/errors/836f8f6a02a0ba35. Report an issue: GitHub.