{"record":{"id":"be4e76dc7f6f90fb","repo":"run-llama/llama_index","slug":"sql-query-tool-query-engine-must-be-an-instance-of-be4e76","errorCode":null,"errorMessage":"sql_query_tool.query_engine must be an instance of BaseSQLTableQueryEngine or NLSQLTableQueryEngine","messagePattern":"sql_query_tool\\.query_engine must be an instance of BaseSQLTableQueryEngine or NLSQLTableQueryEngine","errorType":"exception","errorClass":"ValueError","httpStatus":null,"severity":"error","filePath":"llama-index-core/llama_index/core/query_engine/sql_vector_query_engine.py","lineNumber":97,"sourceCode":"    def __init__(\n        self,\n        sql_query_tool: QueryEngineTool,\n        vector_query_tool: QueryEngineTool,\n        selector: Optional[Union[LLMSingleSelector, PydanticSingleSelector]] = None,\n        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","sourceCodeStart":79,"sourceCodeEnd":115,"githubUrl":"https://github.com/run-llama/llama_index/blob/afd0fef371831f9bda13e5af7167cf4e981278ab/llama-index-core/llama_index/core/query_engine/sql_vector_query_engine.py#L79-L115","documentation":"SQLVectorQueryEngine combines SQL and vector retrieval. Its __init__ first validates that sql_query_tool.query_engine is a BaseSQLTableQueryEngine or NLSQLTableQueryEngine, raising this ValueError if the SQL side cannot actually run SQL queries.","triggerScenarios":"Constructing SQLVectorQueryEngine with sql_query_tool whose query_engine is not an NLSQLTableQueryEngine/BaseSQLTableQueryEngine (e.g. a retriever engine, or arguments swapped with vector_query_tool).","commonSituations":"Swapping the two tool arguments, passing a custom SQL engine that does not subclass the supported bases, or copying example code with mismatched tool construction.","solutions":["Supply NLSQLTableQueryEngine(sql_database=..., tables=[...]) in the sql_query_tool slot","Verify sql_query_tool and vector_query_tool are in the correct positional/named order","Subclass BaseSQLTableQueryEngine for custom SQL engines"],"exampleFix":"// before\nengine = SQLVectorQueryEngine(\n    sql_query_tool=QueryEngineTool.from_defaults(query_engine=vector_engine),\n    vector_query_tool=QueryEngineTool.from_defaults(query_engine=sql_engine),\n)\n\n// after\nengine = SQLVectorQueryEngine(\n    sql_query_tool=QueryEngineTool.from_defaults(\n        query_engine=NLSQLTableQueryEngine(sql_database=sql_db, tables=[\"orders\"])\n    ),\n    vector_query_tool=QueryEngineTool.from_defaults(query_engine=vector_auto_retriever_engine),\n)","handlingStrategy":"type-guard","validationCode":"from llama_index.core.query_engine import BaseSQLTableQueryEngine, NLSQLTableQueryEngine\n\nif not isinstance(\n    sql_query_tool.query_engine,\n    (BaseSQLTableQueryEngine, NLSQLTableQueryEngine),\n):\n    raise TypeError(\"sql side must be NLSQLTableQueryEngine-based\")","typeGuard":"def is_supported_sql_engine(engine) -> bool:\n    from llama_index.core.query_engine import (\n        BaseSQLTableQueryEngine,\n        NLSQLTableQueryEngine,\n    )\n    return isinstance(engine, (BaseSQLTableQueryEngine, NLSQLTableQueryEngine))","tryCatchPattern":null,"preventionTips":["Always build the SQL side via NLSQLTableQueryEngine(sql_database, tables)","Name the tools explicitly (sql_query_tool=..., vector_query_tool=...) to avoid positional swaps","Write a wiring-time validation helper shared across SQL join/vector engines"],"tags":["sql","vector","type-validation","constructor"],"backgroundTag":null,"analyzedSha":"afd0fef371831f9bda13e5af7167cf4e981278ab","analyzedAt":"2026-08-15T05:42:58.429Z","schemaVersion":2},"datasetVersion":"2026-08-15T17:31:12.345Z"}