reflex-dev/reflex · error · ReflexRuntimeError

To access rx.State in frontend components, at least one subc

Error message

To access rx.State in frontend components, at least one subclass of rx.State must be defined in the app.

What it means

compile_app raises ReflexRuntimeError when a component references rx.State (the base class itself) in the frontend but no subclass of rx.State is defined in the app. Accessing rx.State attributes only makes sense once at least one concrete State subclass exists, because Reflex maps state access to a concrete backend state.

Source

Thrown at reflex/compiler/compiler.py:1286

    ]

    # Reinitialize vite config in case runtime options have changed.
    compile_results.append((
        constants.ReactRouter.VITE_CONFIG_FILE,
        frontend_skeleton._compile_vite_config(config),
    ))

    all_imports = compile_ctx.all_imports

    if app._state is None and any(
        code_uses_state_contexts(page_ctx.output_code or "")
        for page_ctx in compile_ctx.compiled_pages.values()
    ):
        msg = (
            "To access rx.State in frontend components, at least one "
            "subclass of rx.State must be defined in the app."
        )
        raise ReflexRuntimeError(msg)
    progress.advance(task)

    app_wrappers = _resolve_app_wrap_components(app, compile_ctx.app_wrap_components)
    app_root = _memoize_stateful_app_wraps(app._app_root(app_wrappers), compile_ctx)
    all_imports = utils.merge_imports(all_imports, app_root._get_all_imports())

    hydrate_fallback = app._resolve_hydrate_fallback()
    hydrate_fallback_export = None
    if hydrate_fallback is not None:
        hydrate_fallback._add_style_recursive(app.style)
        # Compile the fallback through the memo pipeline so it lands in its own
        # JS module; root.jsx then re-exports it as HydrateFallback.
        hydrate_fallback_definition = create_component_memo(
            hydrate_fallback, "hydrate_fallback"
        )
        compile_ctx.auto_memo_components[
            hydrate_fallback_definition.export_name, None
        ] = hydrate_fallback_definition

View on GitHub (pinned to 45b8ed5ab7)

Solutions

1. Define at least one subclass of rx.State (even an empty class AppState(rx.State): pass) in the app
2. Prefer referencing your own state subclass instead of rx.State in components
3. For hydration checks, use rx.State.is_hydrated only after a state subclass exists, or use rx.session_storage-like utilities per docs

Example fix

# before
app = rx.App()
app.add_page(lambda: rx.text(rx.State.is_hydrated))
# after
class AppState(rx.State):
    pass

app = rx.App()
app.add_page(lambda: rx.text(AppState.is_hydrated))

import reflex as rx
assert any(issubclass(c, rx.State) and c is not rx.State for c in rx.State.__subclasses__()), "define a State subclass"

def has_state_subclass() -> bool:
    return any(c is not rx.State for c in rx.State.__subclasses__())

When it happens

Trigger: Using rx.State.something directly in a component (e.g. rx.State.is_hydrated) in an app where every state class is defined but rx.State itself is referenced, while no subclass of rx.State has been declared anywhere in the app code.

Common situations: Small utility apps or examples that use rx.State.is_hydrated without defining any state class; refactoring removed the only State subclass while components still reference rx.State; copy-pasted snippets relying on base-state features.

Related errors

• Cannot directly call background task {name!r}, use `yield {t
• ChildrenTypeError(component=cls.__name__, child=child)
• Do not override _add_style directly. Use add_style instead.
• The component `{comp_name}` only allows the components: {val
• Undefined library for NoSSRComponent

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