reflex-dev/reflex · error · EventFnArgMismatchError

Event {key} only provides {number_of_event_args} arguments,

Error message

Event {key} only provides {number_of_event_args} arguments, but {func_name or user_func} requires at least {number_of_user_args - number_of_user_default_args} arguments to be passed to the event handler.\nSee https://reflex.dev/docs/events/event-arguments/

What it means

When a component event (with a fixed args_spec, e.g. on_change providing one value) is bound to a user function via call_event_fn/call_event_handler, Reflex verifies the event supplies enough arguments for the function's required parameters. Too few event args versus required (non-default) parameters raises EventFnArgMismatchError, with a link to the event-arguments docs.

Source

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

    user_default_args = [
        p.default
        for p in user_func_parameters.values()
        if p.default is not inspect.Parameter.empty
    ]
    number_of_user_args = len(user_args) - number_of_bound_args
    number_of_user_default_args = len(user_default_args) if user_default_args else 0

    number_of_event_args = len(event_spec_args)

    if number_of_user_args - number_of_user_default_args > number_of_event_args:
        msg = (
            f"Event {key} only provides {number_of_event_args} arguments, but "
            f"{func_name or user_func} requires at least {number_of_user_args - number_of_user_default_args} "
            "arguments to be passed to the event handler.\n"
            "See https://reflex.dev/docs/events/event-arguments/"
        )
        raise EventFnArgMismatchError(msg)


def call_event_fn(
    fn: Callable,
    arg_spec: ArgsSpec | Sequence[ArgsSpec],
    key: str | None = None,
) -> list["EventSpec | FunctionVar | EventVar"]:
    """Call a function to a list of event specs.

    The function should return a single event-like value or a heterogeneous
    sequence of event-like values.

    Args:
        fn: The function to call.
        arg_spec: The argument spec for the event trigger.
        key: The key to pass to the event handler.

    Returns:

View on GitHub (pinned to 45b8ed5ab7)

Solutions

Give the extra parameters default values so the event's arg count suffices: def on_change(self, value: str, flag: bool = False)
Match the handler arity to the event's args_spec (check the docs link in the message)
For extra context, capture it in state or via closure instead of extra required params

Example fix

# before
class State(rx.State):
    @rx.event
    def on_change(self, value: str, source: str): ...
# after
class State(rx.State):
    @rx.event
    def on_change(self, value: str, source: str = 'input'): ...

Defensive patterns

Strategy: validation

Validate before calling

import inspect

def arity_ok(fn, n_event_args) -> bool:
    sig = inspect.signature(fn)
    req = sum(1 for p in sig.parameters.values() if p.default is p.empty and p.kind in (p.POSITIONAL_ONLY, p.POSITIONAL_OR_KEYWORD))
    return req <= n_event_args

Type guard

def accepts_event_args(fn, n) -> TypeGuard[Callable]: return arity_ok(fn, n)

Prevention

Give optional context params default values in event handlers
Check the component's args_spec (docs) before binding handlers with multiple required args

When it happens

Trigger: Passing a lambda/function to a trigger that expects the callback to accept the event's args: e.g. using a trigger that provides 1 argument with a function requiring 2 positional params without defaults (lambda a, b: ...).

Common situations: Handling input events (which supply one value) with multi-arg handlers; changing a handler signature to add required params while it stays bound to a single-arg event; passing state handlers with required args to argless events like on_mount.

Related errors

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