reflex-dev/reflex · critical · UserWarning

Do not override _add_style directly. Use add_style instead.

Error message

Do not override _add_style directly. Use add_style instead.

What it means

The cache-based sibling lookup resolves the substate by full name and verifies isinstance against the requested class; mismatch raises StateMismatchError. A state with the same dotted path but different class identity exists in the tree.

Source

Thrown at packages/reflex-base/src/reflex_base/components/component.py:1436

        1. Default style from `_add_style`/`add_style`.
        2. User-defined style from `App.style`.
        3. User-defined style from `Component.style`.
        4. style dict and css props passed to the component instance.

        Args:
            style: A dict from component to styling.
            theme: The theme to apply. (for retro-compatibility with deprecated _apply_theme API)

        Returns:
            The component with the additional style.

        Raises:
            UserWarning: If `_add_style` has been overridden.
        """
        # 1. Default style from `_add_style`/`add_style`.
        if type(self)._add_style != Component._add_style:
            msg = "Do not override _add_style directly. Use add_style instead."
            raise UserWarning(msg)
        new_style = self._add_style()
        style_vars = [new_style._var_data]

        # 2. User-defined style from `App.style`.
        component_style = self._get_component_style(style)
        if component_style:
            new_style.update(component_style)
            style_vars.append(component_style._var_data)

        # 4. style dict and css props passed to the component instance.
        new_style.update(self.style)
        style_vars.append(self.style._var_data)

        new_style._var_data = VarData.merge(*style_vars)

        # Assign the new style
        self.style = new_style
        self._clear_compile_caches()

View on GitHub (pinned to 45b8ed5ab7)

Solutions

1. Ensure each state class is defined exactly once and imported from a single canonical module
2. Fix sys.path/duplicate module aliases that cause double imports
3. Restart the dev server / clear stale modules after moving state definitions

try:
    sub = root.get_substate(path)
except StateMismatchError:
    ...

When it happens

Trigger: Two different classes sharing get_full_name() in one process (duplicate class definitions, module re-imports under different names), so root_state.get_substate returns the wrong class.

Common situations: Defining the same State class in two modules or re-importing an app module under a different path (double-import); hot-reload artifacts creating duplicate class objects.

Related errors

• ChildrenTypeError(component=cls.__name__, child=child)
• The component `{comp_name}` only allows the components: {val
• Undefined library for NoSSRComponent
• Component must have a library to bundle.
• UntypedComputedVarError(var_name=fget.__name__)

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