reflex-dev/reflex · error · TypeError

Expected return type of {fn.__name__} to be a Var, got {fn_r

Error message

Expected return type of {fn.__name__} to be a Var, got {fn_return}.

What it means

A stricter validation path for Var operator functions: the return annotation (after unwrapping its origin) must be Var; anything else raises TypeError naming the offending annotation.

Source

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

        TypeError: If the first argument of the function is not a Var.
        TypeError: If the first argument of the function does not have a generic type
    """
    result_origin_var_type = get_origin(result_var_type) or result_var_type

    if result_origin_var_type in dispatchers:
        fn = dispatchers[result_origin_var_type]
        fn_types = get_type_hints(fn)
        fn_first_arg_type = fn_types.get(
            next(iter(inspect.signature(fn).parameters.values())).name, Any
        )

        fn_return = fn_types.get("return", Any)

        fn_return_origin = get_origin(fn_return) or fn_return

        if fn_return_origin is not Var:
            msg = f"Expected return type of {fn.__name__} to be a Var, got {fn_return}."
            raise TypeError(msg)

        fn_return_generic_args = get_args(fn_return)

        if not fn_return_generic_args:
            msg = f"Expected generic type of {fn_return} to be a type."
            raise TypeError(msg)

        arg_origin = get_origin(fn_first_arg_type) or fn_first_arg_type

        if arg_origin is not Var:
            msg = f"Expected first argument of {fn.__name__} to be a Var, got {fn_first_arg_type}."
            raise TypeError(msg)

        arg_generic_args = get_args(fn_first_arg_type)

        if not arg_generic_args:
            msg = f"Expected generic type of {fn_first_arg_type} to be a type."
            raise TypeError(msg)

View on GitHub (pinned to 45b8ed5ab7)

Solutions

1. Change the return annotation to Var[T]
2. Run pyright/mypy on the extension module to catch annotation mistakes before runtime

Example fix

# before
def items_length(v: Var[list[int]]) -> int: ...
# after
def items_length(v: Var[list[int]]) -> Var[int]: ...

from typing import get_origin
from reflex.vars import Var
rt = fn.__annotations__.get('return', None)
assert (get_origin(rt) or rt) is Var, 'operator fn must return Var[...]'

def is_var_returning(fn) -> bool:
    from typing import get_origin
    from reflex.vars import Var
    rt = fn.__annotations__.get('return')
    return (get_origin(rt) or rt) is Var

When it happens

Trigger: Registering an operator attribute function whose return annotation is not Var[...] (e.g. -> int, -> str, -> None) with the attribute-dispatch decorator.

Common situations: Writing custom Var attributes (like .length() style helpers) and forgetting the Var return annotation.

Related errors

• Expected return type of {fn.__name__} to be a Var, got {orig
• Expected generic type of {fn_return} to be a type.
• Expected first argument of {fn.__name__} to be a Var, got {f
• `@rx.memo` on `{fn.__name__}` must return `rx.Component` or
• `{handler_name}` handler should have a parameter annotated a

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