{"record":{"id":"23e2f3913a4800c3","repo":"run-llama/llama_index","slug":"vector-query-tool-query-engine-must-be-an-instance","errorCode":null,"errorMessage":"vector_query_tool.query_engine must be an instance of RetrieverQueryEngine","messagePattern":"vector_query_tool\\.query_engine must be an instance of RetrieverQueryEngine","errorType":"exception","errorClass":"ValueError","httpStatus":null,"severity":"error","filePath":"llama-index-core/llama_index/core/query_engine/sql_vector_query_engine.py","lineNumber":102,"sourceCode":"        llm: Optional[LLM] = None,\n        sql_vector_synthesis_prompt: Optional[BasePromptTemplate] = None,\n        sql_augment_query_transform: Optional[SQLAugmentQueryTransform] = None,\n        use_sql_vector_synthesis: bool = True,\n        callback_manager: Optional[CallbackManager] = None,\n        verbose: bool = True,\n    ) -> None:\n        \"\"\"Initialize params.\"\"\"\n        # validate that the query engines are of the right type\n        if not isinstance(\n            sql_query_tool.query_engine,\n            (BaseSQLTableQueryEngine, NLSQLTableQueryEngine),\n        ):\n            raise ValueError(\n                \"sql_query_tool.query_engine must be an instance of \"\n                \"BaseSQLTableQueryEngine or NLSQLTableQueryEngine\"\n            )\n        if not isinstance(vector_query_tool.query_engine, RetrieverQueryEngine):\n            raise ValueError(\n                \"vector_query_tool.query_engine must be an instance of \"\n                \"RetrieverQueryEngine\"\n            )\n        if not isinstance(\n            vector_query_tool.query_engine.retriever, VectorIndexAutoRetriever\n        ):\n            raise ValueError(\n                \"vector_query_tool.query_engine.retriever must be an instance \"\n                \"of VectorIndexAutoRetriever\"\n            )\n\n        sql_vector_synthesis_prompt = (\n            sql_vector_synthesis_prompt or DEFAULT_SQL_VECTOR_SYNTHESIS_PROMPT\n        )\n        super().__init__(\n            sql_query_tool,\n            vector_query_tool,\n            selector=selector,","sourceCodeStart":84,"sourceCodeEnd":120,"githubUrl":"https://github.com/run-llama/llama_index/blob/afd0fef371831f9bda13e5af7167cf4e981278ab/llama-index-core/llama_index/core/query_engine/sql_vector_query_engine.py#L84-L120","documentation":"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.","triggerScenarios":"Passing a vector tool whose query_engine is a custom BaseQueryEngine, a SQL engine, or any engine not built from RetrieverQueryEngine(...) when constructing SQLVectorQueryEngine.","commonSituations":"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.","solutions":["Build the vector side as RetrieverQueryEngine.from_args(vector_auto_retriever) where vector_auto_retriever is a VectorIndexAutoRetriever","Do not wrap the vector engine in another engine type before passing it in","Follow the SQLVectorQueryEngine example: vector_query_tool from the RetrieverQueryEngine over the auto retriever"],"exampleFix":"// before\nvector_tool = QueryEngineTool.from_defaults(\n    query_engine=index.as_query_engine(),  # not a RetrieverQueryEngine over auto retriever\n)\nengine = SQLVectorQueryEngine(sql_tool, vector_tool)\n\n// after\nfrom llama_index.core.query_engine import RetrieverQueryEngine\nvector_auto_retriever = VectorIndexAutoRetriever(index, vector_store_info=vector_store_info)\nvector_engine = RetrieverQueryEngine.from_args(vector_auto_retriever)\nvector_tool = QueryEngineTool.from_defaults(query_engine=vector_engine)\nengine = SQLVectorQueryEngine(sql_tool, vector_tool)","handlingStrategy":"type-guard","validationCode":"from llama_index.core.query_engine import RetrieverQueryEngine\n\nif not isinstance(vector_query_tool.query_engine, RetrieverQueryEngine):\n    raise TypeError(\"vector side must be a RetrieverQueryEngine over VectorIndexAutoRetriever\")","typeGuard":"def is_valid_vector_tool(tool) -> bool:\n    from llama_index.core.query_engine import RetrieverQueryEngine\n    return isinstance(tool.query_engine, RetrieverQueryEngine)","tryCatchPattern":null,"preventionTips":["Build the vector engine as RetrieverQueryEngine.from_args(auto_retriever), never index.as_query_engine()","Validate tool types at wiring time, not at first query","Follow the SQLVectorQueryEngine example end-to-end the first time"],"tags":["sql","vector","type-validation","retriever"],"backgroundTag":null,"analyzedSha":"afd0fef371831f9bda13e5af7167cf4e981278ab","analyzedAt":"2026-08-15T05:42:58.429Z","schemaVersion":2},"datasetVersion":"2026-08-15T22:17:37.221Z"}