PrefectHQ/fastmcp · error · ImportError

{name!r} moved to the fastmcp-tasks package. Install it with

Error message

{name!r} moved to the fastmcp-tasks package. Install it with `pip install 'fastmcp[tasks]'` and import from `fastmcp_tasks.dependencies`.

What it means

fastmcp.dependencies defines a module-level __getattr__ that intercepts names moved to the separate fastmcp-tasks package. Requesting CurrentDocket or CurrentWorker without that package installed raises this ImportError with install instructions instead of silently failing.

Source

Thrown at fastmcp_slim/fastmcp/dependencies.py:50

    "CurrentHeaders",
    "CurrentRequest",
    "CycleError",
    "Dependency",
    "Depends",
    "Progress",
    "ProgressLike",
    "Shared",
    "TokenClaim",
]

# Docket-specific dependencies moved to the fastmcp-tasks package. Point users
# there instead of raising a bare AttributeError.
_MOVED_TO_TASKS = {"CurrentDocket", "CurrentWorker"}


def __getattr__(name: str) -> Any:
    if name in _MOVED_TO_TASKS:
        raise ImportError(
            f"{name!r} moved to the fastmcp-tasks package. Install it with "
            f"`pip install 'fastmcp[tasks]'` and import from "
            f"`fastmcp_tasks.dependencies`."
        )
    raise AttributeError(f"module {__name__!r} has no attribute {name!r}")

View on GitHub (pinned to 1f02114297)

Solutions

Install the extra: pip install 'fastmcp[tasks]' (or add it to your dependency group)
Change the import to `from fastmcp_tasks.dependencies import CurrentDocket` (or CurrentWorker)
If you don't need task dependencies, remove the import and use standard fastmcp dependencies instead

Example fix

// before
from fastmcp.dependencies import CurrentDocket

// after
# pip install 'fastmcp[tasks]'
from fastmcp_tasks.dependencies import CurrentDocket

Defensive patterns

Strategy: try-catch

Validate before calling

import importlib.util
if importlib.util.find_spec("fastmcp_tasks") is None:
    raise RuntimeError("Install the tasks extra: pip install 'fastmcp[tasks]'")

Type guard

def tasks_extra_installed() -> bool:
    import importlib.util
    return importlib.util.find_spec("fastmcp_tasks") is not None

Try / catch

try:
    from fastmcp.dependencies import CurrentDocket
except ImportError as e:
    # message tells you to install 'fastmcp[tasks]' and import from fastmcp_tasks.dependencies
    from fastmcp_tasks.dependencies import CurrentDocket  # after installing the extra

Prevention

Add 'fastmcp[tasks]' to your dependency file whenever you use docket/task dependencies
Import CurrentDocket/CurrentWorker directly from fastmcp_tasks.dependencies
Keep extras and code imports in sync in CI (import-lint check)

When it happens

Trigger: `from fastmcp.dependencies import CurrentDocket` (or CurrentWorker) in an environment where the optional fastmcp-tasks extra is not installed.

Common situations: Following task/docket documentation without installing the `fastmcp[tasks]` extra; upgrading fastmcp where these dependencies were split out into the tasks package; fresh environments/CI missing the optional dependency.

Understand the failure class

Background: "X is not installed. Please install it with pip install Y": missing optional dependency errors — ImportError/ValueError raised when a library's optional extra was never installed — this error's family across 22 libraries.

Related errors

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