next/link throws React.Children.only on its children
Error: React.Children.only expected to receive a single React element child.Short answer
React.Children.only accepts exactly one React element and throws for anything else, including an array with one item. A Link or wrapper that calls it fails when it receives text next to an element, two siblings, or a mapped list. Since Next.js 13 Link renders its own anchor, so drop the inner a tag and pass plain children.
Fix it fast
1Find out which cause you have
Find the component that fails and look at what sits directly between its opening and closing tags. Count the children.
grep -rn "<Link" app/ pages/ components/ src/ 2>/dev/null | head -302Match what you see, then jump to its fix
- 1
Code written as <Link href="/about"><a>About</a></Link> after upgrading Next.jsOld-style Link markup with an extra anchor on a current Next.jsFix - 2
The failing wrapper contains an icon and a label, or an element next to a stringMore than one child, or text beside an element, inside a wrapper that needs oneFix - 3
The child is written as {items.map(...)} or a conditional that returns a listThe child is an array, even an array with one itemFix
- 1
What does the error look like?
Error: React.Children.only expected to receive a single React element child.
Cause 1 of 3
Old-style Link markup with an extra anchor on a current Next.js
1Check
Since Next.js 13, Link no longer needs a child a tag. It extends the anchor element itself, so attributes such as className or target are passed straight to it.
grep -rn "<Link[^>]*>\s*<a" app/ pages/ components/ src/ 2>/dev/null2Fix
Run the official codemod to remove the nested anchors, or edit them by hand and move className, target and onClick onto Link.
npx @next/codemod@latest new-link .
// result
<Link href="/about" className="nav">About</Link>3Verify
Start the app and open a page that uses the link.
npm run devConfirmed by nextjs.org
Cause 2 of 3
More than one child, or text beside an element, inside a wrapper that needs one
1Check
Children.only checks that children is a valid single element. A string, or several siblings, makes it throw.
grep -rn "Children.only" node_modules/some-wrapper/ src/ 2>/dev/null | head2Fix
Wrap everything in one element, such as a span, so the wrapper receives a single child.
// before
<Wrapper><Icon /> Settings</Wrapper>
// after
<Wrapper><span><Icon /> Settings</span></Wrapper>3Verify
Reload the page; the error should be gone.
npm run devConfirmed by react.dev
Cause 3 of 3
The child is an array, even an array with one item
1Check
Children.only always throws when it receives an array, such as the return value of a map. It requires a single element, not an array holding a single element.
grep -rn "{.*\.map(" src/ | head2Fix
Render the single element itself, picking the item before JSX, and map to lists outside the wrapper.
const first = items[0];
return <Wrapper><Item data={first} /></Wrapper>;3Verify
Reload the page.
npm run devConfirmed by react.dev
How do I stop it coming back?
- After a Next.js upgrade, run the new-link codemod once and remove leftover anchors.
- When writing a component that calls Children.only, document that it takes exactly one element.
- Pass className and target to Link directly.
Sources
How was this page made?
I drafted this page with AI assistance from the official documents listed under Sources. Every cause above names the document that confirms it. I have not reproduced this fix on a machine of my own yet, so read it as documented guidance, not a test report. Found a mistake? Tell me.
Which stack is behind this page?
Projects of mine built on the same technologies:
- TaxiDexMy own multi-tenant taxi dispatch SaaS: API, dispatcher portal, driver and passenger apps, and the servers underneath.
- QistLockA NestJS and React SaaS driving an Android Device Owner agent that locks financed phones when payments lapse.
- TaskvareA task and project-management suite: React on the web, Flutter on mobile, TypeScript underneath.
Related fixes
Web apps
React warns that a div is nested inside a p tag
Text content does not match server-rendered HTML
A p element may contain only phrasing content, and the HTML parser closes a paragraph as soon as a div, list or other block element starts.
3 causes, each with a fixWeb apps
ESLint says an element in a list is missing its key prop
react/jsx-key
react/jsx-key fires when an element returned from map, Array.from or an array literal has no key.
3 causes, each with a fixWeb apps
There is no tailwind.config.js after installing Tailwind 4 and HeroUI in Next.js
HeroUI components render unstyled
Nothing is broken: Tailwind CSS 4 is configured in CSS and no longer creates tailwind.config.js.
3 causes, each with a fixWeb apps
react-i18next shows the wrong plural form for a count, or prints the key instead of the text
t('item') prints the key item instead of a translated sentence
i18next picks a plural from the count option and looks for keys ending in _one, _other and so on.
4 causes, each with a fixWeb apps
useSession throws because there is no SessionProvider above it
[next-auth]: `useSession` must be wrapped in a <SessionProvider />
useSession reads the session from React Context, and SessionProvider is what creates that context.
3 causes, each with a fixWeb apps
Hydration failed after adding next-themes dark mode
Console reports a server and client mismatch on the html element
next-themes changes the html element and knows the theme only in the browser, so server HTML and client HTML differ.
3 causes, each with a fix