PrefectHQ/fastmcp · critical · ImportError

The `google-genai` package is not installed. Install it with

Error message

The `google-genai` package is not installed. Install it with `pip install 'fastmcp-slim[gemini]'` or add `google-genai` to your dependencies.

What it means

The google_genai sampling handler module imports google.genai at load time; if that package is missing, the module raises ImportError with instructions to install the optional 'gemini' extra. The handler cannot work without the SDK, so failure is immediate at import.

Source

Thrown at fastmcp_slim/fastmcp/client/sampling/handlers/google_genai.py:29

        Blob,
        Candidate,
        Content,
        FunctionCall,
        FunctionCallingConfig,
        FunctionCallingConfigMode,
        FunctionDeclaration,
        FunctionResponse,
        GenerateContentConfig,
        GenerateContentResponse,
        ModelContent,
        Part,
        ThinkingConfig,
        ToolConfig,
        UserContent,
    )
    from google.genai.types import Tool as GoogleTool
except ImportError as e:
    raise ImportError(
        "The `google-genai` package is not installed. "
        "Install it with `pip install 'fastmcp-slim[gemini]'` or add `google-genai` "
        "to your dependencies."
    ) from e

from mcp import ClientSession, ServerSession
from mcp_types import (
    AudioContent,
    CreateMessageResult,
    CreateMessageResultWithTools,
    ImageContent,
    ModelPreferences,
    SamplingMessage,
    SamplingMessageContentBlock,
    StopReason,
    TextContent,
    ToolChoice,
    ToolResultContent,

View on GitHub (pinned to 1f02114297)

Solutions

Run: uv add 'fastmcp-slim[gemini]' or pip install 'fastmcp-slim[gemini]'.
Or add google-genai directly to your project dependencies.
If Gemini isn't needed, use a different sampling handler (Anthropic/OpenAI) whose SDK is installed.
Pin google-genai in your lockfile so environments stay reproducible.

Example fix

// before
pip install fastmcp-slim
// after
pip install 'fastmcp-slim[gemini]'

Defensive patterns

Strategy: validation

Validate before calling

try:
    import google.genai  # noqa: F401
except ImportError:
    raise SystemExit("Install with: pip install 'fastmcp-slim[gemini]'")

Type guard

def gemini_available() -> bool:
    try:
        import google.genai
        return True
    except ImportError:
        return False

Try / catch

try:
    from fastmcp.client.sampling.handlers.google_genai import GoogleGenaiSamplingHandler
except ImportError as e:
    if "google-genai" in str(e):
        handler = FallbackSamplingHandler()
    else:
        raise

Prevention

Install optional extras: fastmcp-slim[gemini]
Declare google-genai in your project's dependencies/lockfile
Verify imports in CI for every environment you deploy to
Import handler modules at startup, not lazily, to fail fast

When it happens

Trigger: Importing fastmcp.client.sampling.handlers.google_genai (or code paths that import it) without google-genai installed — e.g. base fastmcp-slim install without [gemini] extra.

Common situations: Fresh environments/CI without the extra; deploying to a server where optional extras weren't installed; switching handlers to Gemini without updating dependencies.

Related errors

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