reflex-dev/reflex · error · ValueError

f"FormControl can only have at most one child, got {len(chil

Error message

f"FormControl can only have at most one child, got {len(children)} children"

What it means

Radix's high-level rx.form_control wraps exactly one input field (a TextFieldRoot or DebounceInput). Passing two or more children — e.g. a label plus an input plus a description — is rejected because the theme component expects its slots via props, not children.

Source

Thrown at packages/reflex-components-radix/src/reflex_components_radix/primitives/form.py:108

    @classmethod
    def create(cls, *children, **props):
        """Create a Form Control component.

        Args:
            *children: The children of the form.
            **props: The properties of the form.

        Returns:
            The form control component.

        Raises:
            ValueError: If the number of children is greater than 1.
            TypeError: If a child exists but it is not a TextFieldInput.
        """
        if len(children) > 1:
            msg = f"FormControl can only have at most one child, got {len(children)} children"
            raise ValueError(msg)
        for child in children:
            if not isinstance(child, (TextFieldRoot, DebounceInput)):
                msg = "Only Radix TextFieldRoot and DebounceInput are allowed as children of FormControl"
                raise TypeError(msg)
        return super().create(*children, **props)


LiteralMatcher = Literal[
    "badInput",
    "patternMismatch",
    "rangeOverflow",
    "rangeUnderflow",
    "stepMismatch",
    "tooLong",
    "tooShort",
    "typeMismatch",
    "valid",
    "valueMissing",

View on GitHub (pinned to 45b8ed5ab7)

Solutions

1. Keep one child: rx.form_control(rx.text_field.root(rx.text_field.input()))
2. Put label/description in dedicated slots (label=..., helper_text=... style props) instead of extra children
3. Use the lower-level radix primitives if arbitrary layout is needed

Example fix

# before
rx.form_control(rx.text('Email'), rx.text_field.root(rx.text_field.input()))
# after
rx.form_control(
    rx.text_field.root(rx.text_field.input(), type='email'),
    label='Email',
)

assert len(children) <= 1, 'form_control takes at most one child'

When it happens

Trigger: rx.form_control(rx.text('Name'), rx.text_field.root(...)) or any call with 2+ positional children.

Common situations: Porting raw radix form markup where FormControl visibly contains label/input/help-text; assuming it behaves like rx.form with free-form children.

Related errors

• Only Radix TextFieldRoot and DebounceInput are allowed as ch
• Markdown component must have exactly one child containing th
• IconButton requires a child icon. Pass a string as the first
• f"Match did not return a Var: {size_map_var}"
• f"The radio group component takes in a list, got {items_type

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