{"record":{"id":"fe3497bd078e0169","repo":"run-llama/llama_index","slug":"vector-query-tool-query-engine-retriever-must-be-a","errorCode":null,"errorMessage":"vector_query_tool.query_engine.retriever must be an instance of VectorIndexAutoRetriever","messagePattern":"vector_query_tool\\.query_engine\\.retriever must be an instance of VectorIndexAutoRetriever","errorType":"exception","errorClass":"ValueError","httpStatus":null,"severity":"error","filePath":"llama-index-core/llama_index/core/query_engine/sql_vector_query_engine.py","lineNumber":109,"sourceCode":"        \"\"\"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,\n            llm=llm,\n            sql_join_synthesis_prompt=sql_vector_synthesis_prompt,\n            sql_augment_query_transform=sql_augment_query_transform,\n            use_sql_join_synthesis=use_sql_vector_synthesis,\n            callback_manager=callback_manager,\n            verbose=verbose,\n        )","sourceCodeStart":91,"sourceCodeEnd":127,"githubUrl":"https://github.com/run-llama/llama_index/blob/afd0fef371831f9bda13e5af7167cf4e981278ab/llama-index-core/llama_index/core/query_engine/sql_vector_query_engine.py#L91-L127","documentation":"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.","triggerScenarios":"Passing a RetrieverQueryEngine whose retriever is a plain VectorIndexRetriever or any non-VectorIndexAutoRetriever, e.g. index.as_query_engine() without auto-retriever setup.","commonSituations":"Following generic retrieval examples instead of the SQLVectorQueryEngine recipe; forgetting to create VectorIndexAutoRetriever with vector_store_info describing the metadata fields.","solutions":["Create VectorIndexAutoRetriever(index, vector_store_info=VectorStoreInfo(...)) and wrap it: RetrieverQueryEngine.from_args(auto_retriever)","Define vector_store_info with the metadata columns the SQL side will augment queries with","Optionally pass sql_augment_query_transform so the SQL-derived filters are applied to the retriever"],"exampleFix":"// before\nvector_engine = RetrieverQueryEngine(index.as_retriever())  # plain retriever\n\n// after\nfrom llama_index.core.retrievers import VectorIndexAutoRetriever\nfrom llama_index.core.vector_stores import VectorStoreInfo, MetadataInfo\nauto_retriever = VectorIndexAutoRetriever(\n    index,\n    vector_store_info=VectorStoreInfo(\n        content_info=\"company annual-report lines\",\n        metadata_info=[MetadataInfo(name=\"year\", type=\"str\", description=\"Fiscal year\")],\n    ),\n)\nvector_engine = RetrieverQueryEngine.from_args(auto_retriever)","handlingStrategy":"type-guard","validationCode":"from llama_index.core.retrievers import VectorIndexAutoRetriever\nfrom llama_index.core.query_engine import RetrieverQueryEngine\n\nvec_engine = vector_query_tool.query_engine\nassert isinstance(vec_engine, RetrieverQueryEngine) and isinstance(\n    vec_engine.retriever, VectorIndexAutoRetriever\n), \"vector tool must wrap a VectorIndexAutoRetriever\"","typeGuard":"def is_auto_retriever_engine(engine) -> bool:\n    \"\"\"True when engine is a RetrieverQueryEngine over VectorIndexAutoRetriever.\"\"\"\n    from llama_index.core.query_engine import RetrieverQueryEngine\n    from llama_index.core.retrievers import VectorIndexAutoRetriever\n    return (\n        isinstance(engine, RetrieverQueryEngine)\n        and isinstance(engine.retriever, VectorIndexAutoRetriever)\n    )","tryCatchPattern":null,"preventionTips":["Define VectorStoreInfo/MetadataInfo for your metadata fields before creating the auto retriever","Construct via RetrieverQueryEngine.from_args(VectorIndexAutoRetriever(...))","Check engine.retriever type at wiring time so constructor errors are obvious"],"tags":["sql","vector","auto-retriever","type-validation"],"backgroundTag":null,"analyzedSha":"afd0fef371831f9bda13e5af7167cf4e981278ab","analyzedAt":"2026-08-15T05:42:58.429Z","schemaVersion":2},"datasetVersion":"2026-08-15T22:17:37.221Z"}