run-llama/llama_index · error · ValueError

Invalid query mode: {query.mode}

Error message

Invalid query mode: {query.mode}

What it means

SimpleVectorStore.query() implements only a fixed set of VectorStoreQueryMode branches (default top-k similarity and MMR, plus the modes handled above the shown region); any other mode falls through to `raise ValueError(f"Invalid query mode: {query.mode}")`. The message interpolates the mode name at raise time, so the thrown text contains the actual enum value. It signals that the in-memory store does not support the requested retrieval strategy (e.g. sparse, hybrid, SVM regex modes).

Source

Thrown at llama-index-core/llama_index/core/vector_stores/simple.py:310

            )
        elif query.mode == MMR_MODE:
            mmr_threshold = kwargs.get("mmr_threshold")
            top_similarities, top_ids = get_top_k_mmr_embeddings(
                query_embedding,
                embeddings,
                similarity_top_k=query.similarity_top_k,
                embedding_ids=node_ids,
                mmr_threshold=mmr_threshold,
            )
        elif query.mode == VectorStoreQueryMode.DEFAULT:
            top_similarities, top_ids = get_top_k_embeddings(
                query_embedding,
                embeddings,
                similarity_top_k=query.similarity_top_k,
                embedding_ids=node_ids,
            )
        else:
            raise ValueError(f"Invalid query mode: {query.mode}")

        return VectorStoreQueryResult(
            similarities=top_similarities,
            ids=top_ids,
        )

    def persist(
        self,
        persist_path: str = os.path.join(DEFAULT_PERSIST_DIR, DEFAULT_PERSIST_FNAME),
        fs: Optional[fsspec.AbstractFileSystem] = None,
    ) -> None:
        """Persist the SimpleVectorStore to a directory."""
        fs = fs or self._fs
        dirpath = os.path.dirname(persist_path)
        if not fs.exists(dirpath):
            fs.makedirs(dirpath)

        with fs.open(persist_path, "w", encoding="utf-8") as f:

View on GitHub (pinned to afd0fef371)

Solutions

1. Use `VectorStoreQueryMode.DEFAULT` (or MMR, which SimpleVectorStore supports) for the in-memory store.
2. Switch to a vector store integration that implements the mode you need (e.g. Pinecone/Qdrant/Milvus for hybrid or sparse).
3. Check `query.mode` against the store's supported set before querying when the backend is configurable.

Example fix

# before
retriever = VectorIndexRetriever(index=index, vector_store_query_mode=VectorStoreQueryMode.SPARSE)

# after
retriever = VectorIndexRetriever(index=index, vector_store_query_mode=VectorStoreQueryMode.DEFAULT)

SIMPLE_STORE_MODES = {VectorStoreQueryMode.DEFAULT, VectorStoreQueryMode.MMR}

def mode_supported(mode) -> bool:
    return mode in SIMPLE_STORE_MODES

try:
    result = store.query(query)
except ValueError as e:
    if "query mode" in str(e):
        query.mode = VectorStoreQueryMode.DEFAULT
        result = store.query(query)
    else:
        raise

When it happens

Trigger: Constructing a retriever with `vector_store_query_mode=VectorStoreQueryMode.SPARSE` / `HYBRID` / `SVM` / `REGEX` etc. against the default SimpleVectorStore; using `QueryEngine(..., mode=...)` or `VectorStoreQuery(mode=...)` with an unsupported enum member and passing it to `simple_store.query()`.

Common situations: Copy-pasting retriever configs from examples that use Milvus/Weaviate/Pinecone hybrid search; upgrading retrieval strategies without swapping the backend; exploratory code iterating over all VectorStoreQueryMode values.

Related errors

• SimpleVectorStore does not store nodes directly.
• Cannot filter stores that were persisted without metadata. P
• No existing {__name__} found at {persist_path}, skipping loa
• Vector Store only supports exact match filters. Please use E
• get_nodes not implemented

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