{"record":{"id":"92c436c244e15ae4","repo":"mastra-ai/mastra","slug":"mainsidebarnavlink-requires-a-valid-react-element","errorCode":null,"errorMessage":"MainSidebarNavLink requires a valid React element child when `asChild` is true so it can apply `SlottedNavChildProps` and merge `itemClassName`.","messagePattern":"MainSidebarNavLink requires a valid React element child when `asChild` is true so it can apply `SlottedNavChildProps` and merge `itemClassName`\\.","errorType":"exception","errorClass":"Error","httpStatus":null,"severity":"error","filePath":"packages/playground-ui/src/ds/components/MainSidebar/main-sidebar-nav-link.tsx","lineNumber":127,"sourceCode":"  children,\n  link,\n  state,\n  Link,\n  className,\n}: {\n  render?: React.ReactElement<SlottedNavChildProps>;\n  asChild: boolean;\n  children?: React.ReactNode;\n  link?: NavLink;\n  state: SidebarState;\n  Link: LinkComponent;\n  className: string;\n}) {\n  if (render) return React.cloneElement(render, { className: cn(className, render.props.className) });\n\n  if (asChild) {\n    if (!React.isValidElement<SlottedNavChildProps>(children)) {\n      throw new Error(\n        'MainSidebarNavLink requires a valid React element child when `asChild` is true so it can apply `SlottedNavChildProps` and merge `itemClassName`.',\n      );\n    }\n\n    return React.cloneElement(children, { className: cn(className, children.props.className) });\n  }\n\n  if (!link) return children;\n\n  const externalParams = /^(https?:)?\\/\\//.test(link.url) ? { target: '_blank', rel: 'noreferrer' } : {};\n\n  return (\n    <Link href={link.url} {...externalParams} className={className}>\n      {link.icon}\n      <MainSidebarNavLabel state={state}>{link.name}</MainSidebarNavLabel>\n      {children}\n    </Link>\n  );","sourceCodeStart":109,"sourceCodeEnd":145,"githubUrl":"https://github.com/mastra-ai/mastra/blob/75dd419e613fe9c39f846ffc500716141b74fda6/packages/playground-ui/src/ds/components/MainSidebar/main-sidebar-nav-link.tsx#L109-L145","documentation":"When asChild is true, MainSidebarNavLink clones its single React element child to inject className (and SlottedNavChildProps like isActive/data-state). If the child is not a valid React element (text, string, fragment, undefined), cloning is impossible, so the component throws with an explanatory message.","triggerScenarios":"Passing asChild with children that are: a plain string ('Home'), a fragment (<>...</>), a conditional expression evaluating to undefined, or multiple children — anything React.isValidElement rejects.","commonSituations":"Conditional children like {cond && <Link/>} that resolve to false/undefined; passing translated text nodes; wrapping the child in a Fragment 'just to be safe'; refactoring to asChild from a regular-children usage without ensuring a single element.","solutions":["Ensure the child of the asChild link is exactly one valid React element (e.g. <Link/>, <a/>).","Move conditionals outside: {cond ? <MainSidebarNavLink asChild><Link/></MainSidebarNavLink> : null}.","Unwrap fragments — pass the inner element directly.","If you only need text, drop asChild and let the component render its default anchor."],"exampleFix":"// before\n<MainSidebarNavLink asChild href=\"/x\">{isActive && <Link to=\"/x\">X</Link>}</MainSidebarNavLink>\n// after\n{isActive && (\n  <MainSidebarNavLink asChild href=\"/x\"><Link to=\"/x\">X</Link></MainSidebarNavLink>\n)}","handlingStrategy":"validation","validationCode":"const child = props.children;\nif (!React.isValidElement(child)) {\n  // render without asChild or fix the child before enabling slotted props\n  return <MainSidebarNavLink href=\"/x\">{child}</MainSidebarNavLink>;\n}","typeGuard":"function isValidSlottedChild(\n  c: React.ReactNode,\n): c is React.ReactElement<SlottedNavChildProps> {\n  return React.isValidElement<SlottedNavChildProps>(c);\n}","tryCatchPattern":"try {\n  return <MainSidebarNavLink asChild href=\"/x\">{child}</MainSidebarNavLink>;\n} catch {\n  return <MainSidebarNavLink href=\"/x\">{child}</MainSidebarNavLink>; // degrade gracefully\n}","preventionTips":["Always pass exactly one element child (Link/a/button) with asChild — never strings, fragments, or conditionals.","Hoist conditional expressions outside the component instead of `{cond && <El/>}` as the child.","Unwrap Fragments to the single inner element.","Type children as React.ReactElement when asChild is set to catch mistakes at compile time."],"tags":["react","aschild","props-validation","playground-ui"],"backgroundTag":"aschild-invalid-child","analyzedSha":"75dd419e613fe9c39f846ffc500716141b74fda6","analyzedAt":"2026-08-30T00:15:31.844Z","schemaVersion":2},"datasetVersion":"2026-08-30T03:17:51.788Z"}