run-llama/llama_index · error · ValueError

vector_query_tool.query_engine must be an instance of Retrie

Error message

vector_query_tool.query_engine must be an instance of RetrieverQueryEngine

What it means

Second constructor check in SQLVectorQueryEngine: vector_query_tool.query_engine must be a RetrieverQueryEngine, because the engine re-uses that retriever (a VectorIndexAutoRetriever) for metadata-augmented vector search. Any other engine type raises ValueError.

Source

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

        llm: Optional[LLM] = None,
        sql_vector_synthesis_prompt: Optional[BasePromptTemplate] = None,
        sql_augment_query_transform: Optional[SQLAugmentQueryTransform] = None,
        use_sql_vector_synthesis: bool = True,
        callback_manager: Optional[CallbackManager] = None,
        verbose: bool = True,
    ) -> None:
        """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,

View on GitHub (pinned to afd0fef371)

Solutions

1. Build the vector side as RetrieverQueryEngine.from_args(vector_auto_retriever) where vector_auto_retriever is a VectorIndexAutoRetriever
2. Do not wrap the vector engine in another engine type before passing it in
3. Follow the SQLVectorQueryEngine example: vector_query_tool from the RetrieverQueryEngine over the auto retriever

Example fix

// before
vector_tool = QueryEngineTool.from_defaults(
    query_engine=index.as_query_engine(),  # not a RetrieverQueryEngine over auto retriever
)
engine = SQLVectorQueryEngine(sql_tool, vector_tool)

// after
from llama_index.core.query_engine import RetrieverQueryEngine
vector_auto_retriever = VectorIndexAutoRetriever(index, vector_store_info=vector_store_info)
vector_engine = RetrieverQueryEngine.from_args(vector_auto_retriever)
vector_tool = QueryEngineTool.from_defaults(query_engine=vector_engine)
engine = SQLVectorQueryEngine(sql_tool, vector_tool)

from llama_index.core.query_engine import RetrieverQueryEngine

if not isinstance(vector_query_tool.query_engine, RetrieverQueryEngine):
    raise TypeError("vector side must be a RetrieverQueryEngine over VectorIndexAutoRetriever")

def is_valid_vector_tool(tool) -> bool:
    from llama_index.core.query_engine import RetrieverQueryEngine
    return isinstance(tool.query_engine, RetrieverQueryEngine)

When it happens

Trigger: Passing a vector tool whose query_engine is a custom BaseQueryEngine, a SQL engine, or any engine not built from RetrieverQueryEngine(...) when constructing SQLVectorQueryEngine.

Common situations: Wrapping the vector engine in a transformer/router first, or hand-building QueryEngineTool around an incompatible engine instead of using the vector index's default query engine built over a VectorIndexAutoRetriever.

Related errors

• sql_query_tool.query_engine must be an instance of BaseSQLTa
• vector_query_tool.query_engine.retriever must be an instance
• Not supported
• Unknown SQL parser mode: {sql_parser_mode}
• sql_query_tool.query_engine must be an instance of BaseSQLTa

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