facebook/react · error · Error

React.Children.only expected to receive a single React eleme

Error message

React.Children.only expected to receive a single React element child.

What it means

React.Children.only returns its input only when it is exactly one valid React element (isValidElement passes). Strings, numbers, arrays, fragments with multiple children, portals, null, and undefined all fail the check and throw, because consumers of only() (like context providers) need a single real element.

Source

Thrown at packages/react/src/ReactChildren.js:457

}

/**
 * Returns the first child in a collection of children and verifies that there
 * is only one child in the collection.
 *
 * See https://reactjs.org/docs/react-api.html#reactchildrenonly
 *
 * The current implementation of this function assumes that a single child gets
 * passed without a wrapper, but the purpose of this helper function is to
 * abstract away the particular structure of children.
 *
 * @param {?object} children Child collection structure.
 * @return {ReactElement} The first and only `ReactElement` contained in the
 * structure.
 */
function onlyChild<T>(children: T): T {
  if (!isValidElement(children)) {
    throw new Error(
      'React.Children.only expected to receive a single React element child.',
    );
  }

  return children;
}

export {
  forEachChildren as forEach,
  mapChildren as map,
  countChildren as count,
  onlyChild as only,
  toArray,
};

View on GitHub (pinned to eafeac097b)

Solutions

1. Ensure the caller passes exactly one element child, wrapped in a single element if needed
2. Guard before calling: React.isValidElement(children) ? React.Children.only(children) : fallback
3. If multiple children are legitimate, use React.Children.map/toArray instead of only()

Example fix

// before
function Single({children}) {
  return cloneElement(React.Children.only(children), {extra: true});
}
<Single>hi</Single> // throws

// after
<Single><span>hi</span></Single>
// or inside the component:
if (!isValidElement(children)) {
  return <span>{children}</span>;
}

// Guard the single-child contract
function Single({children}) {
  if (!React.isValidElement(children)) {
    return <>{children}</>; // or throw your own descriptive error
  }
  return cloneElement(React.Children.only(children), {extra: true});
}

const isSingleElement = (children: unknown): children is React.ReactElement =>
  React.isValidElement(children);

When it happens

Trigger: React.Children.only(this.props.children) inside a component whose children is a string (<Comp>text</Comp>), an array (<Comp><a/><b/></Comp>), or missing (<Comp />).

Common situations: Strict single-child wrapper components (e.g. cloneElement-based providers) receiving text or no children; conditional children that evaluate to undefined; children passed through an extra HOC that wraps them in an array.

Related errors

• Objects are not valid as a React child (found: ${childrenStr
• The argument must be a React element, but you passed ${eleme

AI-assisted analysis of facebook/react@eafeac097b (2026-08-21). Data as JSON: /api/errors/42132056bacd2a3f. Report an issue: GitHub.