reflex-dev/reflex · warning · ValueError

The component `{child_name}` can only be a child of the comp

Error message

The component `{child_name}` can only be a child of the components: {valid_parent_list}. Got `{comp_name}` instead.

What it means

During serialization, Reflex pickles each state and warns (or raises StateTooLargeError in RAISE perf mode) when the pickle exceeds a size threshold, because huge states slow every event round-trip.

Source

Thrown at packages/reflex-base/src/reflex_base/components/component.py:1643

            if self._valid_children and child_name not in [
                *self._valid_children,
                *allowed_components,
            ]:
                valid_child_list = ", ".join([
                    f"`{v_child}`" for v_child in self._valid_children
                ])
                msg = f"The component `{comp_name}` only allows the components: {valid_child_list} as children. Got `{child_name}` instead."
                raise ValueError(msg)

            if child._valid_parents and all(
                clz_name not in [*child._valid_parents, *allowed_components]
                for clz_name in self._iter_parent_classes_names()
            ):
                valid_parent_list = ", ".join([
                    f"`{v_parent}`" for v_parent in child._valid_parents
                ])
                msg = f"The component `{child_name}` can only be a child of the components: {valid_parent_list}. Got `{comp_name}` instead."
                raise ValueError(msg)

        for child in children:
            validate_child(child)

    @staticmethod
    def _get_vars_from_event_triggers(
        event_triggers: dict[str, EventChain | Var],
    ) -> Iterator[tuple[str, list[Var]]]:
        """Get the Vars associated with each event trigger.

        Args:
            event_triggers: The event triggers from the component instance.

        Yields:
            tuple of (event_name, event_vars)
        """
        for event_trigger, event in event_triggers.items():
            if isinstance(event, Var):

View on GitHub (pinned to 45b8ed5ab7)

Solutions

Move large data out of state (object storage / filesystem, keep only a URL or id in state)
Trim/cap collections stored in state (e.g. keep last N chat messages)
If the size is intentional, set REFLEX_PERF_MODE=warn (default) or off to silence

Example fix

// before
class State(rx.State):
    file_data: str = ""  # base64 blob
// after
class State(rx.State):
    file_url: str = ""  # uploaded to storage

Defensive patterns

Strategy: validation

Validate before calling

import pickle
size = len(pickle.dumps(state))
if size > threshold:
    trim_state()  # prune large fields before continuing

Try / catch

try:
    await state._serialize()
except StateTooLargeError:
    await cleanup_large_fields()

Prevention

Never store file blobs in state; store URLs
Cap growing collections in state
Run with REFLEX_PERF_MODE=warn in CI to catch size regressions

When it happens

Trigger: A state holding large blobs (base64 files, big lists, images) is pickled and exceeds the threshold; behavior depends on REFLEX_PERF_MODE: WARN logs once, RAISE throws StateTooLargeError.

Common situations: Storing uploaded file contents in state vars; accumulating unbounded lists/dicts in state across events; enabling REFLEX_PERF_MODE=raise in CI to catch regressions.

Related errors

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