honojs/hono · error · Error

Children.only() expects only one child

Error message

Children.only() expects only one child

What it means

Children.only() is a React-compatible helper in hono/jsx that returns the single child of a component. It throws unless the children array, after flattening via toArray, contains exactly one element — zero or multiple children both fail.

Source

Thrown at src/jsx/children.ts:15

import type { Child } from './base'

export const toArray = (children: Child): Child[] =>
  Array.isArray(children) ? children : [children]
export const Children = {
  map: (children: Child[], fn: (child: Child, index: number) => Child): Child[] =>
    toArray(children).map(fn),
  forEach: (children: Child[], fn: (child: Child, index: number) => void): void => {
    toArray(children).forEach(fn)
  },
  count: (children: Child[]): number => toArray(children).length,
  only: (_children: Child[]): Child => {
    const children = toArray(_children)
    if (children.length !== 1) {
      throw new Error('Children.only() expects only one child')
    }
    return children[0]
  },
  toArray,
}

View on GitHub (pinned to e2740d5a1b)

Solutions

1. Ensure the component using Children.only receives exactly one child element in every usage
2. Wrap multiple children in a single fragment or container element
3. Guard with Children.count or Children.toArray before calling only, and render a fallback or throw a clearer error

Example fix

// before
function Frame(props: { children: Child[] }) {
  const child = Children.only(props.children) // throws if 0 or 2+ children
  return <div>{child}</div>
}
// after
function Frame(props: { children: Child[] }) {
  const arr = Children.toArray(props.children)
  if (arr.length !== 1) throw new Error(`Frame expects 1 child, got ${arr.length}`)
  return <div>{arr[0]}</div>
}

const children = Children.toArray(props.children)
if (children.length !== 1) throw new RangeError(`expected 1 child, got ${children.length}`)

const hasSingleChild = (c: Child[]): boolean => Children.toArray(c).length === 1

null

When it happens

Trigger: Calling Children.only(children) in a component whose JSX has no children (`<Layout />`), multiple children (`<Layout><A/><B/></Layout>`), or children that flatten to an array of length ≠ 1 (nested arrays, fragments with several items).

Common situations: Writing layout components that expect exactly one child (e.g. a single trigger button) and receiving conditionally rendered or wrapped children; refactoring from Children.map to Children.only; whitespace/text nodes counting as extra children.

Related errors

• Invalid JSX tag name: ${tag}
• Can only set one of `children` or `props.dangerouslySetInner
• Invalid prop '${key}' of type 'function' supplied to '${tag}
• Cannot update an unmounted root
• style sheet not found

AI-assisted analysis of honojs/hono@e2740d5a1b (2026-08-28). Data as JSON: /api/errors/1bdb9682c5d0ea44. Report an issue: GitHub.