reflex-dev/reflex · critical · TypeError

Compiled app root must be a Component.

Error message

Compiled app root must be a Component.

What it means

Internal compile-time invariant in _memoize_stateful_app_wraps: after compiling the app root from app wraps and page context, the result must be a Component instance. It signals that app-level wrappers (AppShell, plugins, app_wrap components) produced something that is not a Component, which would break all downstream code generation.

Source

Thrown at reflex/compiler/compiler.py:1111

            definitions are registered on ``auto_memo_components``.

    Returns:
        The app root with stateful wraps replaced by memo wrappers.
    """
    hooks = CompilerHooks(plugins=(MemoizeStatefulPlugin(),))
    page_context = PageContext(
        name="app_root",
        route=constants.PageNames.APP_ROOT,
        root_component=app_root,
    )
    compiled_root = hooks.compile_component(
        app_root,
        page_context=page_context,
        compile_context=compile_context,
    )
    if not isinstance(compiled_root, Component):
        msg = "Compiled app root must be a Component."
        raise TypeError(msg)
    return compiled_root


def _resolve_radix_themes_plugin(
    app: App,
    plugins: Sequence[Plugin],
) -> tuple[tuple[Plugin, ...], RadixThemesPlugin]:
    """Resolve the effective Radix Themes plugin for the active compile.

    Returns:
        The compiler plugin chain and the effective Radix Themes plugin.
    """
    explicit_plugin = next(
        (plugin for plugin in plugins if isinstance(plugin, RadixThemesPlugin)),
        None,
    )
    if explicit_plugin is not None:
        radix_plugin = explicit_plugin

View on GitHub (pinned to 45b8ed5ab7)

Solutions

1. Audit custom app_wrap/plugin code and ensure wrappers resolve to Component instances
2. Wrap the wrapper's output with rx.fragment() or use into_component-compatible values
3. Update Reflex — internal API changes across versions commonly cause this in plugins
4. Report/check the plugin's compatibility with your Reflex version

When it happens

Trigger: An app_wrap component or plugin-registered wrapper returns a non-Component (e.g. a function or string) from its rendering hook, or custom App subclasses override _app_root in a way that returns a non-Component. Rarely hit by normal application code.

Common situations: Custom plugins adding app wraps incorrectly, monkeypatched or subclassed App internals after a Reflex version upgrade changed the app-wrap pipeline, or third-party libraries returning invalid wrappers.

Related errors

• Match children count mismatch: expected {num_cases + 1} (cas
• f"Match did not return a Var: {size_map_var}"
• Compiled page {route!r} root must be a Component before it c
• To access rx.State in frontend components, at least one subc
• Plugin {plugin_name} is trying to modify {path} but it does

AI-assisted analysis of reflex-dev/reflex@45b8ed5ab7 (2026-08-28). Data as JSON: /api/errors/262ed1f07548d3d8. Report an issue: GitHub.