reflex-dev/reflex · error · TypeError

Expected a mapping type or a dataclass, got {_var_value!r} o

Error message

Expected a mapping type or a dataclass, got {_var_value!r} of type {type(_var_value).__name__}.

What it means

LiteralObjectVar.create accepts only Mapping types (or dataclasses, which are serialized to a mapping). If the passed value is neither a mapping nor serializable into one (the serializer returns a non-mapping), TypeError is raised with the actual type name.

Source

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

        Args:
            _var_value: The value of the var.
            _var_type: The type of the var.
            _var_data: Additional hooks and imports associated with the Var.

        Returns:
            The literal object var.

        Raises:
            TypeError: If the value is not a mapping type or a dataclass.
        """
        if not isinstance(_var_value, collections.abc.Mapping):
            from reflex_base.utils.serializers import serialize

            serialized = serialize(_var_value, get_type=False)
            if not isinstance(serialized, collections.abc.Mapping):
                msg = f"Expected a mapping type or a dataclass, got {_var_value!r} of type {type(_var_value).__name__}."
                raise TypeError(msg)

            return LiteralObjectVar(
                _js_expr="",
                _var_type=(type(_var_value) if _var_type is None else _var_type),
                _var_data=_var_data,
                _var_value=serialized,
            )

        return LiteralObjectVar(
            _js_expr="",
            _var_type=(figure_out_type(_var_value) if _var_type is None else _var_type),
            _var_data=_var_data,
            _var_value=_var_value,
        )


@var_operation
def object_keys_operation(value: ObjectVar):

View on GitHub (pinned to 45b8ed5ab7)

Solutions

Pass an actual dict/Mapping (or dataclass) to the object var API.
Fix the state annotation and stored value to agree (dict field holds dicts).
Register a serializer that converts your custom type to a dict.

Example fix

# before
class State(rx.State):
    config: dict = ["a", "b"]  # list assigned to dict var

# after
class State(rx.State):
    config: dict = {"items": ["a", "b"]}

Defensive patterns

Strategy: type-guard

Validate before calling

import collections.abc as cabc

def is_mapping(v) -> bool:
    return isinstance(v, cabc.Mapping) or hasattr(v, "__dataclass_fields__")

Type guard

import collections.abc as cabc

def is_mapping_or_dataclass(v) -> bool:
    return isinstance(v, cabc.Mapping) or hasattr(v, "__dataclass_fields__")

Prevention

Match state var annotations with the actual values assigned.
Initialize dict vars with {} not [].
Add a startup assertion for the shape of default state values.

When it happens

Trigger: Passing a list, set, string, or arbitrary object where an object var is expected — e.g. rx.Var literal creation from a non-dict, merge()/__getitem__/__getattr__ operations landing on a non-mapping value.

Common situations: Annotating a state var as dict but assigning a list; computed vars returning the wrong shape; passing a pydantic model whose custom serializer returns a scalar; refactors that change a value's type without updating the annotation.

Related errors

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