reflex-dev/reflex · error · ValueError

Return value must be a var or component

Error message

Return value must be a var or component

What it means

The return value of each rx.match case (the last tuple element) must be a Var or a BaseComponent after conversion. Values that cannot be converted to vars (or are None-like) trigger this.

Source

Thrown at packages/reflex-components-core/src/reflex_components_core/core/match.py:178

            *conditions, return_value = case

            conditions_vars: list[Var] = []
            for condition_index, condition in enumerate(conditions):
                if isinstance(condition, BaseComponent):
                    msg = f"Match condition {condition_index} of case {case_index} cannot be a component."
                    raise ValueError(msg)
                conditions_vars.append(cls._create_case_var_with_var_data(condition))

            return_value = (
                cls._create_case_var_with_var_data(return_value)
                if not isinstance(return_value, BaseComponent)
                else return_value
            )

            if not isinstance(return_value, (Var, BaseComponent)):
                msg = "Return value must be a var or component"
                raise ValueError(msg)

            match_cases.append((conditions_vars, return_value))

        return match_cases

    @classmethod
    def _validate_return_types(
        cls, match_cases: list[tuple[list[Var], BaseComponent | Var]]
    ) -> list[tuple[list[Var], Var]] | list[tuple[list[Var], BaseComponent]]:
        """Validate that match cases have the same return types.

        Args:
            match_cases: The match cases.

        Returns:
            The validated match cases.

        Raises:

View on GitHub (pinned to 45b8ed5ab7)

Solutions

1. Return primitives (str/int/float/bool), Var instances, or components from every case
2. Wrap dynamic values with Var.create(...) or reference state vars like State.value
3. Keep all return values the same type so downstream type validation also passes

Example fix

# before
rx.match(State.n, (1, SomeCustomObject()), "none")
# after
rx.match(State.n, (1, "one"), "none")

from reflex.vars import Var
from reflex.components import Component

rv = case[-1]
assert isinstance(rv, (Var, Component)) or Var.create(rv) is not None

def is_valid_return_value(v: Any) -> TypeGuard[Var | Component]:
    from reflex.vars import Var
    from reflex.components import Component
    return isinstance(v, (Var, Component)) or _is_primitive(v)

When it happens

Trigger: Passing a non-convertible object as the last tuple element, such as a plain unconvertible class instance, a dict-like that Var.create rejects, or None where a var/component is expected.

Common situations: Returning arbitrary Python objects (e.g. custom class instances or functions) from match cases instead of strings, numbers, vars, or components.

Related errors

• For cases with return types as Vars, a default case must be
• The condition must be set
• rx.match should have at least one case.
• rx.match should have tuples of cases and one default case as
• A case tuple should have at least a match case element and a

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