run-llama/llama_index · error · ValueError

extra_filters cannot be OR condition

Error message

extra_filters cannot be OR condition

What it means

VectorIndexAutoRetriever.__init__ raises ValueError('extra_filters cannot be OR condition') when extra_filters is provided with extra_filters.condition == FilterCondition.OR. The auto-retriever already synthesizes its own metadata filters from the LLM; combining LLM-generated filters with OR-joined extra filters via the query-spec path is not implemented, so only AND conditions are accepted (the extra filters then narrow the LLM's selection).

Source

Thrown at llama-index-core/llama_index/core/indices/vector_store/retrievers/auto_retriever/auto_retriever.py:108

        self._default_empty_query_vector = default_empty_query_vector
        self._llm = llm or Settings.llm
        callback_manager = callback_manager or Settings.callback_manager

        # prompt
        prompt_template_str = (
            prompt_template_str or DEFAULT_VECTOR_STORE_QUERY_PROMPT_TMPL
        )
        self._output_parser = VectorStoreQueryOutputParser()
        self._prompt: BasePromptTemplate = PromptTemplate(template=prompt_template_str)

        # additional config
        self._max_top_k = max_top_k
        self._similarity_top_k = similarity_top_k
        self._empty_query_top_k = empty_query_top_k
        self._vector_store_query_mode = vector_store_query_mode
        # if extra_filters is OR condition, we don't support that yet
        if extra_filters is not None and extra_filters.condition == FilterCondition.OR:
            raise ValueError("extra_filters cannot be OR condition")
        self._extra_filters = extra_filters or MetadataFilters(filters=[])
        self._kwargs = kwargs
        super().__init__(
            callback_manager=callback_manager,
            object_map=object_map or self._index._object_map,
            objects=objects,
            verbose=verbose,
        )

    def _get_prompts(self) -> PromptDictType:
        """Get prompts."""
        return {
            "prompt": self._prompt,
        }

    def _update_prompts(self, prompts: PromptDictType) -> None:
        """Get prompt modules."""
        if "prompt" in prompts:

View on GitHub (pinned to afd0fef371)

Solutions

1. Use FilterCondition.AND (or omit condition) for extra_filters.
2. If you truly need OR logic across extra filters, precompute a single filter value (e.g. one 'tenant_ids' field with an IN operator filter) or filter results after retrieval.
3. For full OR control, use a plain VectorIndexRetriever with your own MetadataFilters instead of the auto-retriever.

Example fix

# before
filters = MetadataFilters(
    filters=[MetadataFilter(key="tenant", value="a"), MetadataFilter(key="tenant", value="b")],
    condition=FilterCondition.OR,
)
retriever = VectorIndexAutoRetriever(index, extra_filters=filters)  # ValueError

# after
filters = MetadataFilters(filters=[MetadataFilter(key="env", value="prod")])  # AND (default)
retriever = VectorIndexAutoRetriever(index, extra_filters=filters)

from llama_index.core.vector_stores.types import FilterCondition, MetadataFilters

def extra_filters_are_compatible(filters: MetadataFilters) -> bool:
    return filters is None or filters.condition != FilterCondition.OR

When it happens

Trigger: VectorIndexAutoRetriever(index, extra_filters=MetadataFilters(filters=[...], condition=FilterCondition.OR)); note MetadataFilters' default condition is 'and', so this only fires when OR is set explicitly.

Common situations: Trying to scope retrieval to 'tenant_id == A OR tenant_id == B'; multi-tenant or environment-scoping filters written with OR; migrating hand-built MetadataFilters(OR) queries into the auto-retriever.

Related errors

• Must provide either user_msg or chat_history
• Cannot initialize from a vector store that does not store te
• Vector store query result should return at least one of node
• No nodes returned by vector_query
• Cannot initialize from a vector store that does not store te

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