{"record":{"id":"bfb53800632ef2b1","repo":"run-llama/llama_index","slug":"invalid-number-of-children-bfb538","errorCode":null,"errorMessage":"Invalid number of children.","messagePattern":"Invalid number of children\\.","errorType":"validation","errorClass":"ValueError","httpStatus":null,"severity":"error","filePath":"llama-index-core/llama_index/core/indices/tree/inserter.py","lineNumber":38,"sourceCode":"from llama_index.core.storage.docstore import BaseDocumentStore\nfrom llama_index.core.storage.docstore.registry import get_default_docstore\n\n\nclass TreeIndexInserter:\n    \"\"\"LlamaIndex inserter.\"\"\"\n\n    def __init__(\n        self,\n        index_graph: IndexGraph,\n        llm: Optional[LLM] = None,\n        num_children: int = 10,\n        insert_prompt: BasePromptTemplate = DEFAULT_INSERT_PROMPT,\n        summary_prompt: BasePromptTemplate = DEFAULT_SUMMARY_PROMPT,\n        docstore: Optional[BaseDocumentStore] = None,\n    ) -> None:\n        \"\"\"Initialize with params.\"\"\"\n        if num_children < 2:\n            raise ValueError(\"Invalid number of children.\")\n        self.num_children = num_children\n        self.summary_prompt = summary_prompt\n        self.insert_prompt = insert_prompt\n        self.index_graph = index_graph\n        self._llm = llm or Settings.llm\n        self._prompt_helper = Settings._prompt_helper or PromptHelper.from_llm_metadata(\n            self._llm.metadata,\n        )\n        self._docstore = docstore or get_default_docstore()\n\n    def _insert_under_parent_and_consolidate(\n        self, text_node: BaseNode, parent_node: Optional[BaseNode]\n    ) -> None:\n        \"\"\"\n        Insert node under parent and consolidate.\n\n        Consolidation will happen by dividing up child nodes, and creating a new\n        intermediate layer of nodes.","sourceCodeStart":20,"sourceCodeEnd":56,"githubUrl":"https://github.com/run-llama/llama_index/blob/afd0fef371831f9bda13e5af7167cf4e981278ab/llama-index-core/llama_index/core/indices/tree/inserter.py#L20-L56","documentation":"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.","triggerScenarios":"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.","commonSituations":"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'.","solutions":["Pass num_children >= 2 (the default is 10).","If deriving it dynamically, clamp: num_children = max(2, computed_value).","For very small corpora, leave it at the default — the tree still forms correctly."],"exampleFix":"# before\nindex = TreeIndex.from_documents(docs, num_children=1)  # ValueError\n\n# after\nnum_children = max(2, ceil(len(docs) / 5))\nindex = TreeIndex.from_documents(docs, num_children=num_children)","handlingStrategy":"validation","validationCode":"def valid_num_children(n) -> bool:\n    return isinstance(n, int) and n >= 2\n\n# usage:\n# num_children = cfg.get(\"num_children\", 10)\n# if not valid_num_children(num_children): raise ValueError(\"num_children must be >= 2\")","typeGuard":"def is_valid_num_children(n) -> bool:\n    return isinstance(n, int) and not isinstance(n, bool) and n >= 2","tryCatchPattern":null,"preventionTips":["Clamp dynamically computed branching factors: max(2, computed).","Validate config-sourced num_children before constructing TreeIndex/TreeIndexInserter."],"tags":["tree-index","constructor","validation","llama-index"],"backgroundTag":null,"analyzedSha":"afd0fef371831f9bda13e5af7167cf4e981278ab","analyzedAt":"2026-08-15T05:42:58.429Z","schemaVersion":2},"datasetVersion":"2026-08-15T17:31:12.345Z"}