reflex-dev/reflex · error · ValueError

{on_upload_progress} cannot return a var {events}.

Error message

{on_upload_progress} cannot return a var {events}.

What it means

The on_upload_progress lambda is called to build its event chain; if it returns a Var instead of an EventChain/EventSpec, the framework cannot serialize it as an event trigger and rejects it.

Source

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

            on_upload_progress = self.on_upload_progress
            if isinstance(on_upload_progress, EventHandler):
                events = [
                    call_event_handler(
                        on_upload_progress,
                        self.on_upload_progress_args_spec,
                    ),
                ]
            elif isinstance(on_upload_progress, Callable):
                # Call the lambda to get the event chain.
                events = call_event_fn(
                    on_upload_progress, self.on_upload_progress_args_spec
                )
            else:
                msg = f"{on_upload_progress} is not a valid event handler."
                raise ValueError(msg)
            if isinstance(events, Var):
                msg = f"{on_upload_progress} cannot return a var {events}."
                raise ValueError(msg)
            on_upload_progress_chain = EventChain(
                events=[*events],
                args_spec=self.on_upload_progress_args_spec,
            )
            formatted_chain = str(format.format_prop(on_upload_progress_chain))
            spec_args.append(
                (
                    Var(_js_expr="on_upload_progress"),
                    FunctionStringVar(
                        formatted_chain.strip("{}"),
                    ).to(FunctionVar, EventChain),
                ),
            )
        return EventSpec(
            handler=handler,
            client_handler_name=client_handler_name,
            args=tuple(spec_args),
            event_actions=handler.event_actions.copy(),

View on GitHub (pinned to 45b8ed5ab7)

Solutions

1. Make the lambda return an event handler invocation: lambda p: State.set_progress(p.progress)
2. If you only need a value displayed, bind it as a Var on the component, not via on_upload_progress

Example fix

# before
on_upload_progress=lambda e: State.upload_msg
# after
on_upload_progress=lambda e: State.set_upload_msg(e.progress)

# smoke-test the lambda at authoring time
result = my_lambda(fake_event)
assert not hasattr(result, '_var_type'), 'progress lambda must return an event, not a Var'

def returns_event(fn) -> bool: r = fn(_FakeEvent()); return isinstance(r, (EventSpec, EventChain))

When it happens

Trigger: on_upload_progress=lambda p: State.messages (returns a Var) instead of returning an event call.

Common situations: Writing a lambda that indexes state or returns a computed value rather than triggering an event handler call.

Related errors

• @rx.event(background=True) is required for upload_files_chun
• `{handler_name}` handler should have a parameter annotated a
• Event handler {self.fn.__name__} received multiple file uplo
• Event handler {self.fn.__name__} argument {clash!r} conflict
• Invalid event chain: {value!s} of type {value._var_type}

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