PrefectHQ/fastmcp · error · TypeError

Expected a Prefab UI component

Error message

Expected a Prefab UI component

What it means

`prefab_app_from_component` wraps a Prefab UI view component into a Prefab app, and raises this TypeError when the object passed is not an instance of the Prefab component type (or when the Prefab package isn't installed at all, in which case the type lookup returns None). It's a type guard protecting an API that only accepts genuine Prefab UI components.

Source

Thrown at fastmcp_slim/fastmcp/utilities/prefab.py:73

    prefab_types = _get_prefab_types()
    return prefab_types is not None and isinstance(value, prefab_types[0])


def is_prefab_component(value: Any) -> bool:
    """Return whether a value is a Prefab component."""
    if not _could_be_prefab(value):
        return False

    prefab_types = _get_prefab_types()
    return prefab_types is not None and isinstance(value, prefab_types[1])


def prefab_app_from_component(component: Any) -> Any:
    """Wrap a Prefab component in a Prefab app."""
    prefab_types = _get_prefab_types()
    if prefab_types is None or not isinstance(component, prefab_types[1]):
        raise TypeError("Expected a Prefab UI component")
    return prefab_types[0](view=component)

View on GitHub (pinned to 1f02114297)

Solutions

1. Install the Prefab UI extra so the component types are importable (check `_get_prefab_types` requirements / package extras).
2. Return the actual Prefab component instance from your tool — not a dict, wrapper, or an already-wrapped app.
3. Verify the code path: if the tool can return non-UI values, branch so only Prefab components reach `convert_result`.

Example fix

// before
return {"view": my_view}  # plain dict
// after
return my_view  # actual Prefab UI component instance

def ensure_prefab_installed() -> bool:
    from fastmcp.utilities.prefab import _get_prefab_types
    return _get_prefab_types() is not None

def is_prefab_component(obj: object) -> bool:
    from fastmcp.utilities.prefab import _get_prefab_types
    types = _get_prefab_types()
    return types is not None and isinstance(obj, types[1])

try:
    app = prefab_app_from_component(result)
except TypeError as e:
    if "Expected a Prefab UI component" in str(e):
        logger.warning("Tool returned non-Prefab value %r; skipping UI wrap", result)
        app = None
    else:
        raise

When it happens

Trigger: Calling the prefab app path (`__init__` or `convert_result`) with a return value that is not a Prefab component — e.g. a plain dict, a dataclass, or another framework's view object — or with Prefab support not installed (`fastmcp[ui]` extras missing) so `_get_prefab_types()` is None.

Common situations: A tool decorated to return a Prefab UI actually returns a fallback/plain value on some code path; the Prefab dependency wasn't installed; a refactoring replaced the component with a wrapper object; passing a Prefab *app* instead of a *component* (double wrapping attempt).

Related errors

• resource_uri cannot be set on resources — the resource itsel

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