run-llama/llama_index · error · ValueError

num_keywords must be >= 1

Error message

num_keywords must be >= 1

What it means

Raised by KeywordExtractor.__init__ when the keywords parameter (number of keywords the LLM should extract per node, default 5) is less than 1. The count is baked into prompt_template, so a non-positive count is rejected immediately in __init__.

Source

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

    prompt_template: str = Field(
        default=DEFAULT_KEYWORD_EXTRACT_TEMPLATE,
        description="Prompt template to use when generating keywords.",
    )

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

        super().__init__(
            llm=llm or llm_predictor or Settings.llm,
            keywords=keywords,
            prompt_template=prompt_template,
            num_workers=num_workers,
            **kwargs,
        )

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

    async def _aextract_keywords_from_node(self, node: BaseNode) -> Dict[str, str]:
        """Extract keywords from a node and return it's metadata dict."""
        if self.is_text_node_only and not isinstance(node, TextNode):
            return {}

View on GitHub (pinned to afd0fef371)

Solutions

1. Pass keywords >= 1, e.g. KeywordExtractor() for the default of 5.
2. Clamp at the config boundary: keywords = max(1, cfg['keywords']).
3. To disable keyword extraction, exclude the extractor from the pipeline instead of setting 0.

Example fix

# before
extractor = KeywordExtractor(keywords=int(cfg.get("keywords", 0)))

# after
extractor = KeywordExtractor(keywords=max(1, int(cfg.get("keywords", 5))))

num_keywords = int(config.get("keywords", 5))
if num_keywords < 1:
    raise ValueError(f"keywords must be >= 1, got {num_keywords}")
extractor = KeywordExtractor(keywords=num_keywords)

When it happens

Trigger: Constructing KeywordExtractor(keywords=0), typically from a config value, CLI flag, or computed expression that evaluates to zero or a negative number.

Common situations: YAML/JSON pipeline configs with keywords: 0; env-var parsing like int(os.environ.get('NUM_KEYWORDS', '0')); dynamic sizing that yields 0 for tiny documents.

Related errors

• num_nodes 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/2f3d331bcf44c268. Report an issue: GitHub.