run-llama/llama_index · error · ValueError

vector_query_tool.query_engine.retriever must be an instance

Error message

vector_query_tool.query_engine.retriever must be an instance of VectorIndexAutoRetriever

What it means

Third constructor check in SQLVectorQueryEngine: the vector tool's RetrieverQueryEngine must wrap specifically a VectorIndexAutoRetriever, because the engine injects query-time metadata filters (via SQLAugmentQueryTransform) that only that retriever understands.

Source

Thrown at llama-index-core/llama_index/core/query_engine/sql_vector_query_engine.py:109

        """Initialize params."""
        # validate that the query engines are of the right type
        if not isinstance(
            sql_query_tool.query_engine,
            (BaseSQLTableQueryEngine, NLSQLTableQueryEngine),
        ):
            raise ValueError(
                "sql_query_tool.query_engine must be an instance of "
                "BaseSQLTableQueryEngine or NLSQLTableQueryEngine"
            )
        if not isinstance(vector_query_tool.query_engine, RetrieverQueryEngine):
            raise ValueError(
                "vector_query_tool.query_engine must be an instance of "
                "RetrieverQueryEngine"
            )
        if not isinstance(
            vector_query_tool.query_engine.retriever, VectorIndexAutoRetriever
        ):
            raise ValueError(
                "vector_query_tool.query_engine.retriever must be an instance "
                "of VectorIndexAutoRetriever"
            )

        sql_vector_synthesis_prompt = (
            sql_vector_synthesis_prompt or DEFAULT_SQL_VECTOR_SYNTHESIS_PROMPT
        )
        super().__init__(
            sql_query_tool,
            vector_query_tool,
            selector=selector,
            llm=llm,
            sql_join_synthesis_prompt=sql_vector_synthesis_prompt,
            sql_augment_query_transform=sql_augment_query_transform,
            use_sql_join_synthesis=use_sql_vector_synthesis,
            callback_manager=callback_manager,
            verbose=verbose,
        )

View on GitHub (pinned to afd0fef371)

Solutions

1. Create VectorIndexAutoRetriever(index, vector_store_info=VectorStoreInfo(...)) and wrap it: RetrieverQueryEngine.from_args(auto_retriever)
2. Define vector_store_info with the metadata columns the SQL side will augment queries with
3. Optionally pass sql_augment_query_transform so the SQL-derived filters are applied to the retriever

Example fix

// before
vector_engine = RetrieverQueryEngine(index.as_retriever())  # plain retriever

// after
from llama_index.core.retrievers import VectorIndexAutoRetriever
from llama_index.core.vector_stores import VectorStoreInfo, MetadataInfo
auto_retriever = VectorIndexAutoRetriever(
    index,
    vector_store_info=VectorStoreInfo(
        content_info="company annual-report lines",
        metadata_info=[MetadataInfo(name="year", type="str", description="Fiscal year")],
    ),
)
vector_engine = RetrieverQueryEngine.from_args(auto_retriever)

from llama_index.core.retrievers import VectorIndexAutoRetriever
from llama_index.core.query_engine import RetrieverQueryEngine

vec_engine = vector_query_tool.query_engine
assert isinstance(vec_engine, RetrieverQueryEngine) and isinstance(
    vec_engine.retriever, VectorIndexAutoRetriever
), "vector tool must wrap a VectorIndexAutoRetriever"

def is_auto_retriever_engine(engine) -> bool:
    """True when engine is a RetrieverQueryEngine over VectorIndexAutoRetriever."""
    from llama_index.core.query_engine import RetrieverQueryEngine
    from llama_index.core.retrievers import VectorIndexAutoRetriever
    return (
        isinstance(engine, RetrieverQueryEngine)
        and isinstance(engine.retriever, VectorIndexAutoRetriever)
    )

When it happens

Trigger: Passing a RetrieverQueryEngine whose retriever is a plain VectorIndexRetriever or any non-VectorIndexAutoRetriever, e.g. index.as_query_engine() without auto-retriever setup.

Common situations: Following generic retrieval examples instead of the SQLVectorQueryEngine recipe; forgetting to create VectorIndexAutoRetriever with vector_store_info describing the metadata fields.

Related errors

• sql_query_tool.query_engine must be an instance of BaseSQLTa
• vector_query_tool.query_engine must be an instance of Retrie
• sql_query_tool.query_engine must be an instance of BaseSQLTa
• Unexpected type: {type(choice)}
• Unexpected type: {type(query)}

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