run-llama/llama_index · error · ValueError

Invalid number of children.

Error message

Invalid number of children.

What it means

TreeIndexInserter.__init__ (and TreeIndex, which forwards num_children) raises ValueError('Invalid number of children.') when num_children < 2. Each internal tree node must summarize at least two children for the bottom-up consolidation to reduce the node count; num_children=1 would loop forever during insertion/consolidation. The check runs at construction, before any documents are processed.

Source

Thrown at llama-index-core/llama_index/core/indices/tree/inserter.py:38

from llama_index.core.storage.docstore import BaseDocumentStore
from llama_index.core.storage.docstore.registry import get_default_docstore


class TreeIndexInserter:
    """LlamaIndex inserter."""

    def __init__(
        self,
        index_graph: IndexGraph,
        llm: Optional[LLM] = None,
        num_children: int = 10,
        insert_prompt: BasePromptTemplate = DEFAULT_INSERT_PROMPT,
        summary_prompt: BasePromptTemplate = DEFAULT_SUMMARY_PROMPT,
        docstore: Optional[BaseDocumentStore] = None,
    ) -> 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.insert_prompt = insert_prompt
        self.index_graph = index_graph
        self._llm = llm or Settings.llm
        self._prompt_helper = Settings._prompt_helper or PromptHelper.from_llm_metadata(
            self._llm.metadata,
        )
        self._docstore = docstore or get_default_docstore()

    def _insert_under_parent_and_consolidate(
        self, text_node: BaseNode, parent_node: Optional[BaseNode]
    ) -> None:
        """
        Insert node under parent and consolidate.

        Consolidation will happen by dividing up child nodes, and creating a new
        intermediate layer of nodes.

View on GitHub (pinned to afd0fef371)

Solutions

1. Pass num_children >= 2 (the default is 10).
2. If deriving it dynamically, clamp: num_children = max(2, computed_value).
3. For very small corpora, leave it at the default — the tree still forms correctly.

Example fix

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

# after
num_children = max(2, ceil(len(docs) / 5))
index = TreeIndex.from_documents(docs, num_children=num_children)

def valid_num_children(n) -> bool:
    return isinstance(n, int) and n >= 2

# usage:
# num_children = cfg.get("num_children", 10)
# if not valid_num_children(num_children): raise ValueError("num_children must be >= 2")

def is_valid_num_children(n) -> bool:
    return isinstance(n, int) and not isinstance(n, bool) and n >= 2

When it happens

Trigger: TreeIndex.from_documents(docs, num_children=1); TreeIndex(..., num_children=0) passed from a config file default of 0; computing num_children from a formula (e.g. ceil(total/branches)) that yields 1 for small inputs.

Common situations: Auto-tuning branching factors for small document sets; YAML/ENV config with an unset value defaulting to 0 or 1; misunderstanding num_children as 'max leaf nodes per query'.

Related errors

• Invalid number of children.
• Max iterations of {max_iterations} reached! Either something
• 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

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