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

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.

Source

Thrown at llama-index-core/llama_index/core/query_engine/sql_vector_query_engine.py:97

    def __init__(
        self,
        sql_query_tool: QueryEngineTool,
        vector_query_tool: QueryEngineTool,
        selector: Optional[Union[LLMSingleSelector, PydanticSingleSelector]] = None,
        llm: Optional[LLM] = None,
        sql_vector_synthesis_prompt: Optional[BasePromptTemplate] = None,
        sql_augment_query_transform: Optional[SQLAugmentQueryTransform] = None,
        use_sql_vector_synthesis: bool = True,
        callback_manager: Optional[CallbackManager] = None,
        verbose: bool = True,
    ) -> None:
        """Initialize params."""
        # 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"
            )
        if not isinstance(vector_query_tool.query_engine, RetrieverQueryEngine):
            raise ValueError(
                "vector_query_tool.query_engine must be an instance of "
                "RetrieverQueryEngine"
            )
        if not isinstance(
            vector_query_tool.query_engine.retriever, VectorIndexAutoRetriever
        ):
            raise ValueError(
                "vector_query_tool.query_engine.retriever must be an instance "
                "of VectorIndexAutoRetriever"
            )

        sql_vector_synthesis_prompt = (
            sql_vector_synthesis_prompt or DEFAULT_SQL_VECTOR_SYNTHESIS_PROMPT

View on GitHub (pinned to afd0fef371)

Solutions

1. Supply NLSQLTableQueryEngine(sql_database=..., tables=[...]) in the sql_query_tool slot
2. Verify sql_query_tool and vector_query_tool are in the correct positional/named order
3. Subclass BaseSQLTableQueryEngine for custom SQL engines

Example fix

// before
engine = SQLVectorQueryEngine(
    sql_query_tool=QueryEngineTool.from_defaults(query_engine=vector_engine),
    vector_query_tool=QueryEngineTool.from_defaults(query_engine=sql_engine),
)

// after
engine = SQLVectorQueryEngine(
    sql_query_tool=QueryEngineTool.from_defaults(
        query_engine=NLSQLTableQueryEngine(sql_database=sql_db, tables=["orders"])
    ),
    vector_query_tool=QueryEngineTool.from_defaults(query_engine=vector_auto_retriever_engine),
)

from llama_index.core.query_engine import BaseSQLTableQueryEngine, NLSQLTableQueryEngine

if not isinstance(
    sql_query_tool.query_engine,
    (BaseSQLTableQueryEngine, NLSQLTableQueryEngine),
):
    raise TypeError("sql side must be NLSQLTableQueryEngine-based")

def is_supported_sql_engine(engine) -> bool:
    from llama_index.core.query_engine import (
        BaseSQLTableQueryEngine,
        NLSQLTableQueryEngine,
    )
    return isinstance(engine, (BaseSQLTableQueryEngine, NLSQLTableQueryEngine))

When it happens

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

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

Related errors

• sql_query_tool.query_engine must be an instance of BaseSQLTa
• vector_query_tool.query_engine must be an instance of Retrie
• vector_query_tool.query_engine.retriever must be an instance
• nodes must be a list of Node objects.
• sql_database must be provided.

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