reflex-dev/reflex · error · TypeError

Expected first argument of {fn.__name__} to be a Var, got {f

Error message

Expected first argument of {fn.__name__} to be a Var, got {fn_first_arg_type}.

What it means

Same validation as 188 but reports the actual offending first-argument annotation; it fires when the annotation's origin (unwrapped generic origin) is not Var, e.g. list[int] or a plain class.

Source

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

        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,
                _var_data=var_data,
                _var_type=fn_return_type,
            ).guess_type()
            if existing_var is None
            else existing_var._replace(
                _var_type=fn_return_type,

View on GitHub (pinned to 45b8ed5ab7)

Solutions

1. Wrap the first argument annotation in Var[...]
2. For unions/optionals use Var[list[int]] not list[int] | None

Example fix

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

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

def takes_var_first(fn) -> bool:
    import inspect
    from typing import get_origin
    from reflex.vars import Var
    p = next(iter(inspect.signature(fn).parameters.values()))
    a = p.annotation
    return (get_origin(a) or a) is Var

When it happens

Trigger: def op(v: list[int]) -> Var[int] — the first argument is a concrete generic type instead of Var[list[int]].

Common situations: Operators over collections annotated with the element type rather than Var[element type].

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 generic type of {fn_return} to be a type.
• `@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/1a460acdff51add9. Report an issue: GitHub.