run-llama/llama_index · error · ValueError

Unknown retriever mode: {retriever_mode}

Error message

Unknown retriever mode: {retriever_mode}

What it means

KeywordTableIndex.as_retriever() dispatches on a retriever_mode string/enum and only accepts KeywordTableRetrieverMode.DEFAULT ('default'), SIMPLE, and RAKE. Any other value falls through the elif chain and raises ValueError with the offending mode interpolated into the message.

Source

Thrown at llama-index-core/llama_index/core/indices/keyword_table/base.py:127

            KeywordTableGPTRetriever,
            KeywordTableRAKERetriever,
            KeywordTableSimpleRetriever,
        )

        if retriever_mode == KeywordTableRetrieverMode.DEFAULT:
            return KeywordTableGPTRetriever(
                self, object_map=self._object_map, llm=self._llm, **kwargs
            )
        elif retriever_mode == KeywordTableRetrieverMode.SIMPLE:
            return KeywordTableSimpleRetriever(
                self, object_map=self._object_map, **kwargs
            )
        elif retriever_mode == KeywordTableRetrieverMode.RAKE:
            return KeywordTableRAKERetriever(
                self, object_map=self._object_map, **kwargs
            )
        else:
            raise ValueError(f"Unknown retriever mode: {retriever_mode}")

    @abstractmethod
    def _extract_keywords(self, text: str) -> Set[str]:
        """Extract keywords from text."""

    async def _async_extract_keywords(self, text: str) -> Set[str]:
        """Extract keywords from text."""
        # by default just call sync version
        return self._extract_keywords(text)

    def _add_nodes_to_index(
        self,
        index_struct: KeywordTable,
        nodes: Sequence[BaseNode],
        show_progress: bool = False,
    ) -> None:
        """Add document to index."""
        nodes_with_progress = get_tqdm_iterable(

View on GitHub (pinned to afd0fef371)

Solutions

1. Use a valid KeywordTableRetrieverMode value: KeywordTableRetrieverMode.DEFAULT, .SIMPLE, or .RAKE (or the strings 'default', 'simple', 'rake').
2. Import and reference the enum instead of hardcoding strings: from llama_index.core.indices.keyword_table import KeywordTableRetrieverMode.
3. If you need embedding-based retrieval, use a VectorStoreIndex or SummaryIndex(embedding mode) rather than a keyword table mode.

Example fix

# before
retriever = kt_index.as_retriever(retriever_mode="embedding")

# after
from llama_index.core.indices.keyword_table import KeywordTableRetrieverMode
retriever = kt_index.as_retriever(retriever_mode=KeywordTableRetrieverMode.RAKE)

from llama_index.core.indices.keyword_table import KeywordTableRetrieverMode

VALID = {m.value for m in KeywordTableRetrieverMode}
assert retriever_mode in VALID or retriever_mode in list(KeywordTableRetrieverMode), retriever_mode
retriever = kt_index.as_retriever(retriever_mode=retriever_mode)

try:
    retriever = kt_index.as_retriever(retriever_mode=mode)
except ValueError as e:
    if "Unknown retriever mode" in str(e):
        retriever = kt_index.as_retriever()  # fall back to default mode
    else:
        raise

When it happens

Trigger: KeywordTableIndex(...).as_retriever(retriever_mode='embedding'), 'llm', or a typo like 'rake ' / 'Simple'; passing a mode valid for a different index type (e.g. a ListIndex mode) into a keyword table index; constructing the retriever from a config string that has drifted from the enum values.

Common situations: Config-driven retriever selection where the same mode string is applied to several index types; copy-pasting retriever code between VectorStoreIndex and KeywordTableIndex; newer/renamed modes after a llama-index version upgrade.

Related errors

• Unknown retriever mode: {retriever_mode}
• Cannot initialize from a vector store that does not store te
• llm must start with str 'local' or of type LLM or BaseLangua
• Token limit must be set and greater than 0.
• Token limit for full-text messages must be set and greater t

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