The error explained

This error happens when a React component expects one child element but receives multiple elements or something that is not a valid React element. Many components use React.Children.only() internally even if you never call it directly in your code.

Common mistake: Forgetting to map arrays

The most frequent cause is passing an array directly as children without mapping it first.

// This causes the error
const ErrorExample = () => {
  const items = ["Item 1", "Item 2", "Item 3"];

  return (
    <Modal>
      {items} {/* Passing array directly */}
    </Modal>
  );
};

React treats the array as a single item, but it is not a valid React element. The component tries to use React.Children.only() on this array and crashes.

How to fix array issues

Always map arrays to React elements and wrap them in a container:

// Fixed version
const FixedExample = () => {
  const items = ["Item 1", "Item 2", "Item 3"];

  return (
    <Modal>
      <div>
        {items.map((item, index) => (
          <div key={index}>{item}</div>
        ))}
      </div>
    </Modal>
  );
};

Other common causes

Spreading array items

// This causes the error
<SomeComponent>
  {[...items]} {/* Spreads multiple items directly */}
</SomeComponent>

Incorrect conditional rendering

// This causes the error
<ComponentThatExpectsOneChild>
  {condition &&
    <h1>Title</h1>
    <p>Content</p>
  }
</ComponentThatExpectsOneChild>

The correct approach is to wrap multiple elements:

<ComponentThatExpectsOneChild>
  {condition && (
    <div>
      <h1>Title</h1>
      <p>Content</p>
    </div>
  )}
</ComponentThatExpectsOneChild>

Components that often cause this error

These components often use Children.only internally:

• Modal components

• Portals

• Tooltips

• Context providers

• Animation wrappers

Quick fixes checklist

When you see this error:

1. Check for arrays passed directly as children

2. Make sure you use .map() on any arrays

3. Wrap multiple elements in a single container

4. Check your conditional rendering syntax

5. Make sure all JSX expressions are properly wrapped with parentheses

These small mistakes are easy to make but can be fixed quickly once you know what to look for.