run-llama/llama_index · error · ValueError

num_nodes must be >= 1

Error message

num_nodes must be >= 1

What it means

Raised by TitleExtractor.__init__ when the nodes parameter (the number of nodes/documents to combine into a generated title, default 5) is less than 1. A title is produced by feeding `nodes` chunks to the LLM with node_template/combine_template, so zero documents makes the prompt meaningless and is rejected at construction time.

Source

Thrown at llama-index-core/llama_index/core/extractors/metadata_extractors.py:98

    combine_template: str = Field(
        default=DEFAULT_TITLE_COMBINE_TEMPLATE,
        description="The prompt template to merge titles with.",
    )

    def __init__(
        self,
        llm: Optional[LLM] = None,
        # TODO: llm_predictor arg is deprecated
        llm_predictor: Optional[LLM] = None,
        nodes: int = 5,
        node_template: str = DEFAULT_TITLE_NODE_TEMPLATE,
        combine_template: str = DEFAULT_TITLE_COMBINE_TEMPLATE,
        num_workers: int = DEFAULT_NUM_WORKERS,
        **kwargs: Any,
    ) -> None:
        """Init params."""
        if nodes < 1:
            raise ValueError("num_nodes must be >= 1")

        super().__init__(
            llm=llm or llm_predictor or Settings.llm,
            nodes=nodes,
            node_template=node_template,
            combine_template=combine_template,
            num_workers=num_workers,
            **kwargs,
        )

    @classmethod
    def class_name(cls) -> str:
        return "TitleExtractor"

    async def aextract(self, nodes: Sequence[BaseNode]) -> List[Dict]:
        nodes_by_doc_id = self.separate_nodes_by_ref_id(nodes)
        titles_by_doc_id = await self.extract_titles(nodes_by_doc_id)
        return [{"document_title": titles_by_doc_id[node.ref_doc_id]} for node in nodes]

View on GitHub (pinned to afd0fef371)

Solutions

1. Pass nodes >= 1, e.g. the default TitleExtractor() or TitleExtractor(nodes=5).
2. Validate/ clamp the value at the config boundary: nodes = max(1, configured_nodes).
3. If the intent was 'no title extraction', remove TitleExtractor from the transformation pipeline rather than zeroing nodes.

Example fix

# before
extractor = TitleExtractor(nodes=max(0, num_docs - 10))

# after
extractor = TitleExtractor(nodes=max(1, num_docs - 10))
# or omit TitleExtractor entirely when num_docs <= 10

num_nodes = int(config.get("title_nodes", 5))
if num_nodes < 1:
    raise ValueError(f"title_nodes must be >= 1, got {num_nodes}")
extractor = TitleExtractor(nodes=num_nodes)

When it happens

Trigger: Constructing TitleExtractor(nodes=0) — often because a variable (e.g. len(some_list) computed before data loads, or a CLI arg parsed as 0) is passed straight into the constructor.

Common situations: Config files with nodes: 0 copied from a template; arithmetic like max(0, n - k) producing 0; argparse with a default of 0 for a --title-nodes flag.

Related errors

• num_keywords must be >= 1
• questions must be >= 1
• 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/0f576fb49f521cf2. Report an issue: GitHub.