{"record":{"id":"42132056bacd2a3f","repo":"facebook/react","slug":"react-children-only-expected-to-receive-a-single-r","errorCode":null,"errorMessage":"React.Children.only expected to receive a single React element child.","messagePattern":"React\\.Children\\.only expected to receive a single React element child\\.","errorType":"exception","errorClass":"Error","httpStatus":null,"severity":"error","filePath":"packages/react/src/ReactChildren.js","lineNumber":457,"sourceCode":"}\n\n/**\n * Returns the first child in a collection of children and verifies that there\n * is only one child in the collection.\n *\n * See https://reactjs.org/docs/react-api.html#reactchildrenonly\n *\n * The current implementation of this function assumes that a single child gets\n * passed without a wrapper, but the purpose of this helper function is to\n * abstract away the particular structure of children.\n *\n * @param {?object} children Child collection structure.\n * @return {ReactElement} The first and only `ReactElement` contained in the\n * structure.\n */\nfunction onlyChild<T>(children: T): T {\n  if (!isValidElement(children)) {\n    throw new Error(\n      'React.Children.only expected to receive a single React element child.',\n    );\n  }\n\n  return children;\n}\n\nexport {\n  forEachChildren as forEach,\n  mapChildren as map,\n  countChildren as count,\n  onlyChild as only,\n  toArray,\n};\n","sourceCodeStart":439,"sourceCodeEnd":472,"githubUrl":"https://github.com/facebook/react/blob/eafeac097ba51e1eab809c07102126bd5f8e5425/packages/react/src/ReactChildren.js#L439-L472","documentation":"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.","triggerScenarios":"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 />).","commonSituations":"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.","solutions":["Ensure the caller passes exactly one element child, wrapped in a single element if needed","Guard before calling: React.isValidElement(children) ? React.Children.only(children) : fallback","If multiple children are legitimate, use React.Children.map/toArray instead of only()"],"exampleFix":"// before\nfunction Single({children}) {\n  return cloneElement(React.Children.only(children), {extra: true});\n}\n<Single>hi</Single> // throws\n\n// after\n<Single><span>hi</span></Single>\n// or inside the component:\nif (!isValidElement(children)) {\n  return <span>{children}</span>;\n}","handlingStrategy":"type-guard","validationCode":"// Guard the single-child contract\nfunction Single({children}) {\n  if (!React.isValidElement(children)) {\n    return <>{children}</>; // or throw your own descriptive error\n  }\n  return cloneElement(React.Children.only(children), {extra: true});\n}","typeGuard":"const isSingleElement = (children: unknown): children is React.ReactElement =>\n  React.isValidElement(children);","tryCatchPattern":null,"preventionTips":["Document the exactly-one-element contract on the component and its prop types","In tests, always pass a single wrapped element child to components that use Children.only"],"tags":["react-children","children-only","single-child","isvalidelement"],"backgroundTag":"children-only-single-element","analyzedSha":"eafeac097ba51e1eab809c07102126bd5f8e5425","analyzedAt":"2026-08-21T22:01:08.818Z","schemaVersion":2},"datasetVersion":"2026-08-21T23:17:16.201Z"}