reflex-dev/reflex · error · TypeError

Could not compare types {args_types_without_vars[i]} and {ca

Error message

Could not compare types {args_types_without_vars[i]} and {callback_param_type} for argument {arg}{callback_name_context}{key_context}.

What it means

When binding a callback/event handler to a component prop, Reflex compares the handler's parameter types with the arg types the component provides; if Python's issubclass check between the two types itself raises TypeError (e.g. unrelated generic alias combinations or unparameterized generics), the comparison error is re-raised with both types and the argument name.

Source

Thrown at packages/reflex-base/src/reflex_base/event/__init__.py:1999

        # check that args of event handler are matching the spec if type hints are provided
        for i, arg in enumerate(callback_params_names[: len(args_types_without_vars)]):
            if arg not in callback_param_name_to_type:
                continue

            type_match_found.setdefault(arg, False)
            callback_param_type = callback_param_name_to_type[arg]

            try:
                compare_result = typehint_issubclass(
                    args_types_without_vars[i], callback_param_type
                ) or _is_on_submit_mapping_event_arg_compatible_with_typed_dict(
                    args_types_without_vars[i], callback_param_type, key
                )
            except TypeError as te:
                callback_name_context = f" of {callback_name}" if callback_name else ""
                key_context = f" for {key}" if key else ""
                msg = f"Could not compare types {args_types_without_vars[i]} and {callback_param_type} for argument {arg}{callback_name_context}{key_context}."
                raise TypeError(msg) from te

            if compare_result:
                type_match_found[arg] = True
                continue
            type_match_found[arg] = False
            as_annotated_in = (
                f" as annotated in {callback_name}" if callback_name else ""
            )
            delayed_exceptions.append(
                EventHandlerArgTypeMismatchError(
                    f"Event handler {key} expects {args_types_without_vars[i]} for argument {arg} but got {callback_param_type}{as_annotated_in} instead."
                )
            )

        if all(type_match_found.values()):
            delayed_exceptions.clear()
            if event_spec_index:
                args = get_args(provided_event_types[0])

View on GitHub (pinned to 45b8ed5ab7)

Solutions

1. Annotate the handler parameter with the exact parameterized type the callback provides (e.g. list[str] instead of list, dict[str, Any] instead of dict)
2. Simplify/avoid exotic typing constructs in handler signatures used as component callbacks
3. Update Reflex — newer releases widen compatible type pairs

Example fix

# before
class State(rx.State):
    @rx.event
    def on_change(self, value: list): ...
# after
from typing import Any
class State(rx.State):
    @rx.event
    def on_change(self, value: list[str]): ...

# pre-check that issubclass works for your annotation pair
import typing
try:
    typing.get_type_hints(fn)
except Exception:
    raise  # fix annotations before binding as callback

def safe_param_annotation(t) -> TypeGuard[type]: return isinstance(t, type) or typing.get_origin(t) is not None

try:
    rx.select(options, on_change=State.pick)
except TypeError as e:
    if 'Could not compare types' in str(e):
        # re-annotate handler params with parameterized generics and retry
        ...

When it happens

Trigger: Passing a handler with parameter annotations like dict (bare generic) or complex typing constructs to props such as on_change/on_select where the component supplies a parameterized generic type, causing issubclass(A, B) TypeError.

Common situations: Upgrading Reflex versions where component callback arg types became parameterized generics while user handlers kept bare annotations; using custom Generic classes in handler signatures.

Related errors

• `rx.EventHandler` parameters are only supported on component
• `children` in `{fn_name}` cannot be an `rx.EventHandler`; us
• `rx.EventHandler` parameter `{parameter.name}` in `{fn_name}
• @rx.event(background=True) is required for upload_files_chun
• `{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/b293683ee5cee91e. Report an issue: GitHub.