PrefectHQ/fastmcp · error · RuntimeError

No FastMCP server instance in context

Error message

No FastMCP server instance in context

What it means

get_server() resolves the current FastMCP instance from the _current_server context variable (a weak reference) after first checking any configured task-worker resolver. This RuntimeError is thrown when no server reference has been set for the current execution context. FastMCP throws instead of returning None to make misused APIs fail fast.

Source

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

    In a background-task worker the tasks extension's resolver is consulted
    first, so a mounted-child task resolves to the child server rather than the
    root that started the worker (#3571).

    Returns:
        The active FastMCP server

    Raises:
        RuntimeError: If no server in context
    """
    resolver = _worker_server_resolver
    if resolver is not None:
        worker_server = resolver()
        if worker_server is not None:
            return worker_server

    server_ref = _current_server.get()
    if server_ref is None:
        raise RuntimeError("No FastMCP server instance in context")
    server = server_ref()
    if server is None:
        raise RuntimeError("FastMCP server instance is no longer available")
    return server


async def get_session(session_id: str) -> Session:
    """Resolve and validate a `Session` for an explicit `session_id`.

    Pair with a `session_id: SessionId` tool argument (the agent obtains an id
    from `create_session` and passes it back). For a single per-user bucket with
    nothing for the agent to pass, inject `session: UserSession` instead.

    State is keyed by `(principal, session_id)`: the authenticated principal is
    the isolation wall and `session_id` organizes sessions within it. The id must
    have been minted by `create_session` under the current principal; an id that
    was never created, or created under a different principal, raises
    `InvalidSession` rather than resolving to a fresh empty bucket (the specific

View on GitHub (pinned to 1f02114297)

Solutions

1. Call get_server() only from within request handlers or other code executed under a running FastMCP server.
2. In tests, establish the context with an in-memory Client(server) or set the server contextvar in a fixture.
3. Pass the FastMCP instance explicitly to helpers that need it instead of relying on the contextvar.

Example fix

// before
server = get_server()  # at import time
// after
def build(server: FastMCP) -> None: ...  # explicit injection

try:
    server = get_server()
except RuntimeError as e:
    if "No FastMCP server instance in context" in str(e):
        server = None
    else:
        raise

When it happens

Trigger: Calling get_server() outside any server-managed execution context — e.g. in plain scripts, tests without a server contextvar, or code running before the server sets _current_server.

Common situations: Calling server-dependent helpers during module import; running tool helpers in an ad-hoc asyncio script; tests invoking dependency functions directly without Client(server).

Related errors

• FastMCP instance is no longer available
• No active context found.
• FastMCP server instance is no longer available
• OAuth callback handler could not be started
• Client is not connected. Use the 'async with client:' contex

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