run-llama/llama_index · error · ValueError

sql_query_tool.query_engine must be an instance of BaseSQLTa

Error message

sql_query_tool.query_engine must be an instance of BaseSQLTableQueryEngine or NLSQLTableQueryEngine

What it means

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.

Source

Thrown at llama-index-core/llama_index/core/query_engine/sql_join_query_engine.py:212

        sql_query_tool: QueryEngineTool,
        other_query_tool: QueryEngineTool,
        selector: Optional[Union[LLMSingleSelector, PydanticSingleSelector]] = None,
        llm: Optional[LLM] = None,
        sql_join_synthesis_prompt: Optional[BasePromptTemplate] = None,
        sql_augment_query_transform: Optional[SQLAugmentQueryTransform] = None,
        use_sql_join_synthesis: bool = True,
        callback_manager: Optional[CallbackManager] = None,
        verbose: bool = True,
        streaming: bool = False,
    ) -> None:
        """Initialize params."""
        super().__init__(callback_manager=callback_manager)
        # 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"
            )
        self._sql_query_tool = sql_query_tool
        self._other_query_tool = other_query_tool

        self._llm = llm or Settings.llm

        self._selector = selector or get_selector_from_llm(self._llm, is_multi=False)  # type: ignore
        assert isinstance(self._selector, (LLMSingleSelector, PydanticSingleSelector))

        self._sql_join_synthesis_prompt = (
            sql_join_synthesis_prompt or DEFAULT_SQL_JOIN_SYNTHESIS_PROMPT
        )
        self._sql_augment_query_transform = (
            sql_augment_query_transform or SQLAugmentQueryTransform(llm=self._llm)
        )
        self._use_sql_join_synthesis = use_sql_join_synthesis

View on GitHub (pinned to afd0fef371)

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

Example fix

// before
sql_tool = QueryEngineTool.from_defaults(
    query_engine=vector_engine,  # wrong slot/engine
)
join_engine = SQLJoinQueryEngine(sql_tool, other_tool)

// after
sql_tool = QueryEngineTool.from_defaults(
    query_engine=NLSQLTableQueryEngine(sql_database=sql_db, tables=["orders"]),
)
join_engine = SQLJoinQueryEngine(sql_tool, other_tool)

Defensive patterns

Strategy: type-guard

Validate before calling

from llama_index.core.query_engine import BaseSQLTableQueryEngine, NLSQLTableQueryEngine

assert isinstance(
    sql_query_tool.query_engine,
    (BaseSQLTableQueryEngine, NLSQLTableQueryEngine),
), "sql_query_tool must wrap an NLSQLTableQueryEngine/BaseSQLTableQueryEngine"

Type guard

def is_valid_sql_join_sql_tool(tool) -> bool:
    """SQLJoinQueryEngine accepts only these SQL engines in the sql slot."""
    from llama_index.core.query_engine import (
        BaseSQLTableQueryEngine,
        NLSQLTableQueryEngine,
    )
    return isinstance(
        tool.query_engine, (BaseSQLTableQueryEngine, NLSQLTableQueryEngine)
    )

Prevention

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

When it happens

Trigger: 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.

Common situations: 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.

Related errors

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