reflex-dev/reflex · error · RuntimeError

Provide a single child for DebounceInput, such as rx.input()

Error message

Provide a single child for DebounceInput, such as rx.input() or rx.text_area()

What it means

`rx.debounce_input()` wraps exactly one input child (rx.input, rx.text_area, etc.) to debounce its on_change events. Passing zero children, multiple children, or a fragment triggers this RuntimeError at creation time.

Source

Thrown at packages/reflex-components-core/src/reflex_components_core/core/debounce.py:84

        the child, and then neuter the child's render method so it produces no output.

        Args:
            *children: The child component to wrap.
            **props: The component props.

        Returns:
            The DebounceInput component.

        Raises:
            RuntimeError: unless exactly one child element is provided.
            ValueError: if the child element does not have an on_change handler.
        """
        if len(children) != 1:
            msg = (
                "Provide a single child for DebounceInput, such as rx.input() or "
                "rx.text_area()"
            )
            raise RuntimeError(msg)

        child = children[0]
        if "on_change" not in child.event_triggers:
            msg = "DebounceInput child requires an on_change handler"
            raise ValueError(msg)

        # Carry known props and event_triggers from the child.
        props_from_child = {
            p: getattr(child, p)
            for p in cls.get_props()
            if getattr(child, p, None) is not None
        }
        props[EventTriggers.ON_CHANGE] = child.event_triggers.pop(
            EventTriggers.ON_CHANGE
        )
        props = {**props_from_child, **props}

        # Carry all other child props directly via custom_attrs

View on GitHub (pinned to 45b8ed5ab7)

Solutions

1. Wrap exactly one input component: rx.debounce_input(rx.input(value=State.val, on_change=State.set_val))
2. Place extra elements as siblings: rx.hstack(rx.debounce_input(rx.input(...)), rx.icon('search'))
3. For multiple inputs, use one debounce_input per input

Example fix

// before
rx.debounce_input(rx.input(...), rx.text('chars'))
// after
rx.hstack(rx.debounce_input(rx.input(...)), rx.text('chars'))

assert len(children) == 1, 'debounce_input takes exactly one input child'

When it happens

Trigger: `rx.debounce_input()` with no child; `rx.debounce_input(rx.input(...), rx.icon(...))`; passing children as a list.

Common situations: Adding decorative siblings (icons, labels) inside debounce_input instead of around it; forgetting the child during refactoring.

Related errors

• DebounceInput child requires an on_change handler
• Must provide children to the html component.
• ChildrenTypeError(component=cls.__name__, child=child)
• Do not override _add_style directly. Use add_style instead.
• The component `{comp_name}` cannot have `{child_name}` as a

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