{"record":{"id":"c5644264ebcd4f04","repo":"run-llama/llama_index","slug":"sql-query-tool-query-engine-must-be-an-instance-of","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_join_query_engine.py","lineNumber":212,"sourceCode":"        sql_query_tool: QueryEngineTool,\n        other_query_tool: QueryEngineTool,\n        selector: Optional[Union[LLMSingleSelector, PydanticSingleSelector]] = None,\n        llm: Optional[LLM] = None,\n        sql_join_synthesis_prompt: Optional[BasePromptTemplate] = None,\n        sql_augment_query_transform: Optional[SQLAugmentQueryTransform] = None,\n        use_sql_join_synthesis: bool = True,\n        callback_manager: Optional[CallbackManager] = None,\n        verbose: bool = True,\n        streaming: bool = False,\n    ) -> None:\n        \"\"\"Initialize params.\"\"\"\n        super().__init__(callback_manager=callback_manager)\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        self._sql_query_tool = sql_query_tool\n        self._other_query_tool = other_query_tool\n\n        self._llm = llm or Settings.llm\n\n        self._selector = selector or get_selector_from_llm(self._llm, is_multi=False)  # type: ignore\n        assert isinstance(self._selector, (LLMSingleSelector, PydanticSingleSelector))\n\n        self._sql_join_synthesis_prompt = (\n            sql_join_synthesis_prompt or DEFAULT_SQL_JOIN_SYNTHESIS_PROMPT\n        )\n        self._sql_augment_query_transform = (\n            sql_augment_query_transform or SQLAugmentQueryTransform(llm=self._llm)\n        )\n        self._use_sql_join_synthesis = use_sql_join_synthesis","sourceCodeStart":194,"sourceCodeEnd":230,"githubUrl":"https://github.com/run-llama/llama_index/blob/afd0fef371831f9bda13e5af7167cf4e981278ab/llama-index-core/llama_index/core/query_engine/sql_join_query_engine.py#L194-L230","documentation":"SQLJoinQueryEngine joins a SQL query engine with another query engine. Its __init__ validates that sql_query_tool.query_engine is a BaseSQLTableQueryEngine or NLSQLTableQueryEngine (i.e. capable of the SQL-side operations the join synthesis needs) and raises ValueError otherwise.","triggerScenarios":"Passing a QueryEngineTool whose query_engine is e.g. a RetrieverQueryEngine, SQLContextQueryEngine of an unsupported subclass, or a custom engine in the sql_query_tool slot when constructing SQLJoinQueryEngine.","commonSituations":"Swapping the sql_query_tool and other_query_tool arguments by mistake, or supplying a plain SQLBrowserQueryEngine / custom SQL engine not derived from the supported base classes.","solutions":["Pass an NLSQLTableQueryEngine (or BaseSQLTableQueryEngine subclass) in sql_query_tool, e.g. NLSQLTableQueryEngine(sql_database=..., tables=[...])","Double-check argument order: the SQL engine goes in sql_query_tool, the non-SQL engine in other_query_tool","If using a custom SQL engine, subclass BaseSQLTableQueryEngine so the isinstance check passes"],"exampleFix":"// before\nsql_tool = QueryEngineTool.from_defaults(\n    query_engine=vector_engine,  # wrong slot/engine\n)\njoin_engine = SQLJoinQueryEngine(sql_tool, other_tool)\n\n// after\nsql_tool = QueryEngineTool.from_defaults(\n    query_engine=NLSQLTableQueryEngine(sql_database=sql_db, tables=[\"orders\"]),\n)\njoin_engine = SQLJoinQueryEngine(sql_tool, other_tool)","handlingStrategy":"type-guard","validationCode":"from llama_index.core.query_engine import BaseSQLTableQueryEngine, NLSQLTableQueryEngine\n\nassert isinstance(\n    sql_query_tool.query_engine,\n    (BaseSQLTableQueryEngine, NLSQLTableQueryEngine),\n), \"sql_query_tool must wrap an NLSQLTableQueryEngine/BaseSQLTableQueryEngine\"","typeGuard":"def is_valid_sql_join_sql_tool(tool) -> bool:\n    \"\"\"SQLJoinQueryEngine accepts only these SQL engines in the sql slot.\"\"\"\n    from llama_index.core.query_engine import (\n        BaseSQLTableQueryEngine,\n        NLSQLTableQueryEngine,\n    )\n    return isinstance(\n        tool.query_engine, (BaseSQLTableQueryEngine, NLSQLTableQueryEngine)\n    )","tryCatchPattern":null,"preventionTips":["Construct the SQL tool first with NLSQLTableQueryEngine, then pass it as the first argument","Run the isinstance checks yourself at wiring time to fail with clearer context","Remember the same check exists in SQLVectorQueryEngine — write one helper and reuse"],"tags":["sql","join","type-validation","constructor"],"backgroundTag":null,"analyzedSha":"afd0fef371831f9bda13e5af7167cf4e981278ab","analyzedAt":"2026-08-15T05:42:58.429Z","schemaVersion":2},"datasetVersion":"2026-08-15T22:17:37.221Z"}