PrefectHQ/fastmcp · error · ImportError

CodeMode requires pydantic-monty for the Monty sandbox provi

Error message

CodeMode requires pydantic-monty for the Monty sandbox provider. Install it with `fastmcp[code-mode]` or pass a custom SandboxProvider.

What it means

CodeMode transform's default sandbox provider runs generated code in the Monty sandbox from the pydantic-monty package. If that package isn't installed, run() raises this ImportError pointing to the `fastmcp[code-mode]` extra or the option of supplying a custom SandboxProvider.

Source

Thrown at fastmcp_slim/fastmcp/experimental/transforms/code_mode.py:153

    ) -> None:
        # Copy the baseline so each provider owns its dict — `limits` is a
        # mutable public attribute, and sharing the module-level object would
        # let one provider's edits leak into every other default provider.
        self.limits: ResourceLimits | None = (
            _DEFAULT_LIMITS.copy() if isinstance(limits, _UnsetType) else limits
        )

    async def run(
        self,
        code: str,
        *,
        inputs: dict[str, Any] | None = None,
        external_functions: dict[str, Callable[..., Any]] | None = None,
    ) -> Any:
        try:
            pydantic_monty = importlib.import_module("pydantic_monty")
        except ModuleNotFoundError as exc:
            raise ImportError(
                "CodeMode requires pydantic-monty for the Monty sandbox provider. "
                "Install it with `fastmcp[code-mode]` or pass a custom SandboxProvider."
            ) from exc

        inputs = inputs or {}
        async_functions = {
            key: _ensure_async(value)
            for key, value in (external_functions or {}).items()
        }

        monty = pydantic_monty.Monty(code, inputs=list(inputs))
        future = asyncio.ensure_future(
            self._run_monty(
                monty,
                inputs=inputs or None,
                external_functions=async_functions or None,
            )
        )

View on GitHub (pinned to 1f02114297)

Solutions

  1. Install the extra: pip install 'fastmcp[code-mode]' (or add pydantic-monty directly)
  2. Pass a custom SandboxProvider to CodeModeTransform that doesn't require pydantic-monty
  3. Add `fastmcp[code-mode]` to your project's dependency spec so environments get it automatically

Example fix

// before
transform = CodeModeTransform()  # ImportError at run()

// after
# pip install 'fastmcp[code-mode]'
transform = CodeModeTransform()  # works with default Monty sandbox
Defensive patterns

Strategy: fallback

Validate before calling

import importlib.util
if importlib.util.find_spec("pydantic_monty") is None and sandbox_provider is None:
    raise RuntimeError("Install 'fastmcp[code-mode]' or provide a custom SandboxProvider")

Type guard

def code_mode_ready(transform) -> bool:
    import importlib.util
    return importlib.util.find_spec("pydantic_monty") is not None or type(transform.sandbox_provider).__name__ != "MontySandboxProvider"

Try / catch

try:
    result = await transform.execute(code)
except ImportError as e:
    if "pydantic-monty" in str(e):
        raise RuntimeError("Install the code-mode extra: fastmcp[code-mode]") from e
    raise

Prevention

When it happens

Trigger: Calling CodeModeTransform.execute() (which invokes run()) without pydantic-monty installed and without a custom sandbox_provider configured.

Common situations: Installing fastmcp without the code-mode extra; deploying to an environment where optional extras were pruned; enabling code mode in a server whose dependencies were pinned before the extra was added.

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