Maaz Zindani

Loading the index…

↑↓ move↵ openesc close4072 pages
Next.js and React

next/link throws React.Children.only on its children

ErrorError: 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.

  • Applies to Next.js 15, Next.js 16, React 19
  • Updated
  • By Maaz Zindani, Senior Software Engineer

Fix it fast

  1. 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 -30
  2. 2Match what you see, then jump to its fix

    1. 1Code 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. 2The 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. 3The child is written as {items.map(...)} or a conditional that returns a listThe child is an array, even an array with one itemFix

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/null

2Fix

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 dev

Confirmed by nextjs.org

Did this fix it?

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 | head

2Fix

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 dev

Confirmed by react.dev

Did this fix it?

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/ | head

2Fix

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 dev

Confirmed by react.dev

Did this fix it?

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:

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 fix

Web 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

Next step

Want this handled for good?

I look after servers, apps and releases end to end. Tell me what keeps breaking.