PrefectHQ/fastmcp · error · ImportError

FileUpload requires prefab-ui. Install with: pip install 'fa

Error message

FileUpload requires prefab-ui. Install with: pip install 'fastmcp[apps]'

What it means

fastmcp.apps.file_upload imports prefab-ui components (Small, Text, Else/ForEach/If, rx values) at module load. Without prefab_ui installed, the ImportError is re-raised with this install hint, so the FileUpload app cannot be used until the optional extra is present.

Source

Thrown at fastmcp_slim/fastmcp/apps/file_upload.py:58

        H3,
        Badge,
        Button,
        Card,
        CardContent,
        CardFooter,
        CardHeader,
        Column,
        DropZone,
        Muted,
        Row,
        Separator,
        Small,
        Text,
    )
    from prefab_ui.components.control_flow import Else, ForEach, If
    from prefab_ui.rx import ERROR, RESULT, STATE, Rx
except ImportError as _exc:
    raise ImportError(
        "FileUpload requires prefab-ui. Install with: pip install 'fastmcp[apps]'"
    ) from _exc

import base64
from datetime import datetime, timezone
from typing import Any

from fastmcp.apps.app import FastMCPApp
from fastmcp.server.context import Context

_TEXT_EXTENSIONS = frozenset(
    (".csv", ".json", ".txt", ".md", ".py", ".yaml", ".yml", ".toml")
)


def _b64_decoded_size(b64: str) -> int:
    """Return the exact decoded byte-length of a base64 string without decoding it."""
    n = len(b64)

View on GitHub (pinned to 1f02114297)

Solutions

1. Install with: `pip install 'fastmcp[apps]'`.
2. Verify prefab_ui is importable in the running interpreter/venv.
3. Gate the import of file_upload behind an availability check if prefab-ui is optional in your app.

Example fix

// before
from fastmcp.apps.file_upload import FileUpload
// after
pip install 'fastmcp[apps]'
from fastmcp.apps.file_upload import FileUpload

try:
    import prefab_ui  # noqa
except ImportError:
    prefab_ui = None

try:
    from fastmcp.apps.file_upload import FileUpload
except ImportError as e:
    FileUpload = None
    logger.warning("FileUpload unavailable: install 'fastmcp[apps]'")

When it happens

Trigger: `from fastmcp.apps.file_upload import FileUpload` or any import of the module in an environment lacking prefab-ui.

Common situations: Production images without the [apps] extra; missing dependency after dependency refresh; trying FileUpload from a minimal fastmcp install.

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

• Approval requires prefab-ui. Install with: pip install 'fast
• Choice requires prefab-ui. Install with: pip install 'fastmc
• {name!r} moved to the fastmcp-tasks package. Install it with
• CodeMode requires pydantic-monty for the Monty sandbox provi
• {feature} requires the `azure` extra. Install with: pip inst

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