PrefectHQ/fastmcp · error · ImportError

{feature} requires the `azure` extra. Install with: pip inst

Error message

{feature} requires the `azure` extra. Install with: pip install 'fastmcp[azure]'

What it means

OBO features (EntraOBOToken, get_obo_credential) depend on the optional azure-identity package. FastMCP keeps it out of core dependencies; _require_azure_identity probes the import and raises ImportError with install instructions when it's absent, chaining the original ImportError.

Source

Thrown at fastmcp_slim/fastmcp/server/auth/providers/azure.py:815

        prefixed = []
        for scope in effective_scopes:
            if scope in OIDC_SCOPES or "://" in scope or "/" in scope:
                prefixed.append(scope)
            else:
                prefixed.append(f"{self._identifier_uri}/{scope}")
        return prefixed


# --- Dependency injection support ---
# These require fastmcp[azure] extra for azure-identity


def _require_azure_identity(feature: str) -> None:
    """Raise ImportError with install instructions if azure-identity is not available."""
    try:
        import azure.identity  # noqa: F401
    except ImportError as e:
        raise ImportError(
            f"{feature} requires the `azure` extra. "
            "Install with: pip install 'fastmcp[azure]'"
        ) from e


def _find_azure_provider(auth: AuthProvider | None) -> AzureProvider | None:
    """Extract an AzureProvider from an auth provider, unwrapping MultiAuth if needed."""
    if isinstance(auth, AzureProvider):
        return auth

    if isinstance(auth, MultiAuth) and isinstance(auth.server, AzureProvider):
        return auth.server

    return None


class _EntraOBOToken(Dependency[str]):
    """Dependency that performs OBO token exchange for Microsoft Entra.

View on GitHub (pinned to 1f02114297)

Solutions

Install the extra: pip install 'fastmcp[azure]' (or add azure-identity to your requirements).
Update your dependency manifest (pyproject/requirements/uv add 'fastmcp[azure]') so deployments include it.
Rebuild/redeploy the container image after adding the dependency.

Example fix

// before
pip install fastmcp
// after
pip install "fastmcp[azure]"

Defensive patterns

Strategy: try-catch

Validate before calling

import importlib.util
if importlib.util.find_spec("azure.identity") is None:
    raise SystemExit("Install with: pip install 'fastmcp[azure]'")

Try / catch

try:
    async with EntraOBOToken(scopes=["api"]) as t:
        ...
except ImportError as e:
    logger.error("azure-identity missing; install fastmcp[azure]")
    raise

Prevention

Add 'fastmcp[azure]' to pyproject/requirements, not bare fastmcp
Verify optional extras resolve in CI with a clean install
Keep dev and production dependency manifests in sync

When it happens

Trigger: Entering EntraOBOToken or calling get_obo_credential in an environment where fastmcp was installed without the [azure] extra (azure.identity import fails).

Common situations: Deploying to a fresh container/Lambda with only `pip install fastmcp`; CI installs from a lock file generated without the extra; local dev has azure-identity but production doesn't.

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/aeb0ce5d069013ee. Report an issue: GitHub.