reflex-dev/reflex · error · TypeError

Expected generic type of {fn_return} to be a type.

Error message

Expected generic type of {fn_return} to be a type.

What it means

The first argument of a Var operator/attribute function must be annotated as a Var (or Var[...]); the validator raises TypeError when the first parameter's annotation origin is not Var.

Source

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

        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)

        fn_return_type = fn_return_generic_args[0]

        var = (
            Var(
                field_name,

View on GitHub (pinned to 45b8ed5ab7)

Solutions

1. Annotate the first parameter as Var[...], e.g. v: Var[str]
2. Add from __future__ import annotations so string annotations resolve correctly

Example fix

# before
def shout(v: str) -> Var[str]: ...
# after
def shout(v: Var[str]) -> Var[str]: ...

import inspect
from typing import get_origin
from reflex.vars import Var
first = next(iter(inspect.signature(fn).parameters.values()))
assert (get_origin(first.annotation) or first.annotation) is Var, 'first arg must be Var[...]'

When it happens

Trigger: Defining an operator function whose first parameter is annotated as a plain Python type, e.g. def fn(v: str) -> Var[str].

Common situations: Custom operators written as if they operated on raw Python values instead of Vars.

Related errors

• Expected return type of {fn.__name__} to be a Var, got {orig
• Expected return type of {fn.__name__} to be a Var, got {fn_r
• 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/f05bd942ea180415. Report an issue: GitHub.