run-llama/llama_index · error · ValueError

Invalid number of children.

Error message

Invalid number of children.

What it means

Tree-index builders (BaseTreeBuilder, used by TreeIndex) partition leaf nodes into parent summaries; num_children < 2 makes hierarchical folding impossible (each parent needs at least two children to reduce). The constructor rejects num_children less than 2 with ValueError.

Source

Thrown at llama-index-core/llama_index/core/indices/common_tree/base.py:43

    GPT tree index builder.

    Helper class to build the tree-structured index,
    or to synthesize an answer.

    """

    def __init__(
        self,
        num_children: int,
        summary_prompt: BasePromptTemplate,
        llm: Optional[LLM] = None,
        docstore: Optional[BaseDocumentStore] = None,
        show_progress: bool = False,
        use_async: bool = False,
    ) -> None:
        """Initialize with params."""
        if num_children < 2:
            raise ValueError("Invalid number of children.")
        self.num_children = num_children
        self.summary_prompt = summary_prompt
        self._llm = llm or Settings.llm
        self._prompt_helper = Settings._prompt_helper or PromptHelper.from_llm_metadata(
            self._llm.metadata,
        )
        self._callback_manager = Settings.callback_manager
        self._use_async = use_async
        self._show_progress = show_progress
        self._docstore = docstore or get_default_docstore()

    @property
    def docstore(self) -> BaseDocumentStore:
        """Return docstore."""
        return self._docstore

    def build_from_nodes(
        self,

View on GitHub (pinned to afd0fef371)

Solutions

1. Set num_children to at least 2 (typical values are 8–20 depending on token limits).
2. If you don't want a hierarchical summary structure, use VectorStoreIndex instead of TreeIndex.
3. Validate config values at load time with a minimum bound check.

Example fix

# before
index = TreeIndex.from_documents(docs, num_children=1)  # ValueError

# after
index = TreeIndex.from_documents(docs, num_children=10)

if not isinstance(num_children, int) or num_children < 2:
    raise ValueError("num_children must be an integer >= 2")

When it happens

Trigger: Constructing TreeIndex with num_children=1 or 0 (e.g. TreeIndex.from_documents(docs, num_children=1)); passing num_children=0 hoping to disable summarization; computing num_children dynamically and hitting an edge case.

Common situations: Tuning tree fan-out for small documents; CLI/config-driven setups where 0 or 1 slips in as a default; misunderstanding num_children=0 as 'no summarization layer'.

Related errors

• Invalid number of children.
• All agents must have a name in a multi-agent workflow
• All agents must have a description in a multi-agent workflow
• Initial state is not supported per-agent in AgentWorkflow
• Exactly one root agent must be provided

AI-assisted analysis of run-llama/llama_index@afd0fef371 (2026-08-15). Data as JSON: /api/errors/c9e407c51c5857da. Report an issue: GitHub.