reflex-dev/reflex · error · HybridPropertyError

Hybrid property '{self.__property_name}' of state '{state_cl

Error message

Hybrid property '{self.__property_name}' of state '{state_cls.__name__}' accessed backend-only var '{name}' while building its frontend value. Backend vars (prefixed with '_') exist only on the server and cannot be referenced from a hybrid property's frontend logic. Use a regular var, or provide a separate frontend implementation with '@{self.__property_name}.var'.

What it means

A rx.hybrid_property builds both a backend (Python) and a frontend (JS) value from one property. Its frontend implementation is traced through __getattr__ on the state class; if it references a backend-only var (name starting with '_'), there is no way to render that value on the client, so HybridPropertyError is raised.

Source

Thrown at packages/reflex-base/src/reflex_base/vars/hybrid_property.py:52

            name: The attribute accessed on the state inside the hybrid property.

        Returns:
            The class-level value (e.g. a frontend var) from the state.

        Raises:
            HybridPropertyError: If a backend (underscore-prefixed) var is accessed.
        """
        state_cls = self.__state_cls
        if name in state_cls.backend_vars:
            msg = (
                f"Hybrid property '{self.__property_name}' of state "
                f"'{state_cls.__name__}' accessed backend-only var '{name}' while "
                f"building its frontend value. Backend vars (prefixed with '_') exist "
                f"only on the server and cannot be referenced from a hybrid property's "
                f"frontend logic. Use a regular var, or provide a separate frontend "
                f"implementation with '@{self.__property_name}.var'."
            )
            raise HybridPropertyError(msg)
        return getattr(state_cls, name)


class HybridProperty(property):
    """A hybrid property that can also be used in frontend/as var."""

    # The optional var function for the property.
    _var: Callable[[Any], Var] | None = None

    def _get_var(self, owner: Any) -> Var:
        """Get the frontend Var for the property.

        The ``owner`` is the object the property is accessed on at the var level:
        either the class (for class-level access, e.g. ``State.full_name``) or an
        ``ObjectVar`` (for attribute access on an object var, e.g. ``State.info.a_b``).
        Attribute access on ``owner`` inside the getter/var function resolves to Vars.

        Args:

View on GitHub (pinned to 45b8ed5ab7)

Solutions

1. Rename the backend var to a regular (non-underscore) var if it is safe to expose to the client.
2. Provide a separate frontend implementation with `@<property_name>.var` that only uses frontend-visible vars.
3. Move the backend-var logic into a separate backend computed var and have the hybrid property reference that result indirectly.

Example fix

# before
class State(rx.State):
    _token: str = ""
    @rx.hybrid_property
    def header(self) -> str:
        return f"Bearer {self._token}"

# after
class State(rx.State):
    _token: str = ""
    @rx.hybrid_property
    def header(self) -> str:
        return f"Bearer {self.token}"
    @header.var(deps=[_token])
    def header(self) -> str:
        return f"Bearer {self._token}"  # backend-only path

def uses_only_frontend_vars(fn) -> bool:
    import inspect
    src = inspect.getsource(fn)
    return "._" not in src.replace("self._var", "")  # crude check for backend var refs

def references_backend_var(name: str) -> bool:
    return name.startswith("_")

When it happens

Trigger: Defining a hybrid property whose getter accesses a backend var like `self._internal` (or `State._internal`) — e.g. `@rx.hybrid_property def display(self): return f"{self._count}{self._suffix}"` where `_suffix` is backend.

Common situations: Migrating a property that used private/internal state vars to hybrid_property; accidentally including a '_'-prefixed var in f-strings or expressions inside the property; assuming backend vars are readable in frontend rendering like in regular computed vars.

Related errors

• HybridProperty has no getter function
• Frontend process has no stdout.
• Frontend did not start
• Named props cannot be used with custom thresholds
• ChildrenTypeError(component=cls.__name__, child=child)

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