What causes "Unknown query mode: {query_mode}" in run-llama/llama_index?

Use the enum members: from llama_index.core.indices.struct_store.sql_query import SQLQueryMode; index.as_query_engine(query_mode=SQLQueryMode.SQL).

run-llama/llama_index · error · ValueError

Unknown query mode: {query_mode}

Error message

Unknown query mode: {query_mode}

What it means

SQLStructStoreIndex.as_query_engine(query_mode=...) raises ValueError(f'Unknown query mode: {query_mode}') when query_mode matches neither SQLQueryMode.NL nor SQLQueryMode.SQL. The comparison is against enum members; the enum values are the strings 'nl' and 'sql', so only those two exact strings coerce successfully. Any other string (e.g. 'NL', 'default', 'sql_only') falls through to the else branch.

Source

Thrown at llama-index-core/llama_index/core/indices/struct_store/sql.py:165

    def as_query_engine(
        self,
        llm: Optional[LLMType] = None,
        query_mode: Union[str, SQLQueryMode] = SQLQueryMode.NL,
        **kwargs: Any,
    ) -> BaseQueryEngine:
        # NOTE: lazy import
        from llama_index.core.indices.struct_store.sql_query import (
            NLStructStoreQueryEngine,
            SQLStructStoreQueryEngine,
        )

        if query_mode == SQLQueryMode.NL:
            return NLStructStoreQueryEngine(self, **kwargs)
        elif query_mode == SQLQueryMode.SQL:
            return SQLStructStoreQueryEngine(self, **kwargs)
        else:
            raise ValueError(f"Unknown query mode: {query_mode}")


GPTSQLStructStoreIndex = SQLStructStoreIndex

View on GitHub (pinned to afd0fef371)

Solutions

Use the enum members: from llama_index.core.indices.struct_store.sql_query import SQLQueryMode; index.as_query_engine(query_mode=SQLQueryMode.SQL).
If using strings, use exactly 'nl' or 'sql' (lowercase), which coerce to the enum.
For SQL-dry-run behavior use query_engine = index.as_query_engine(); query_engine.sql_only = True (or pass sql_only via kwargs to NLStructStoreQueryEngine) instead of inventing a query mode.

Example fix

# before
engine = index.as_query_engine(query_mode="SQL")  # ValueError

# after
from llama_index.core.indices.struct_store.sql_query import SQLQueryMode
engine = index.as_query_engine(query_mode=SQLQueryMode.SQL)

Defensive patterns

Strategy: type-guard

Validate before calling

from llama_index.core.indices.struct_store.sql_query import SQLQueryMode

VALID_SQL_QUERY_MODES = {SQLQueryMode.NL, SQLQueryMode.SQL}

def safe_as_query_engine(index, query_mode=SQLQueryMode.NL, **kw):
    if isinstance(query_mode, str):
        query_mode = SQLQueryMode(query_mode)  # raises early with a clear message
    assert query_mode in VALID_SQL_QUERY_MODES
    return index.as_query_engine(query_mode=query_mode, **kw)

Type guard

from llama_index.core.indices.struct_store.sql_query import SQLQueryMode

def is_valid_sql_query_mode(m) -> bool:
    try:
        return SQLQueryMode(m) in (SQLQueryMode.NL, SQLQueryMode.SQL)
    except ValueError:
        return False

Prevention

Always pass SQLQueryMode enum members instead of strings.
If strings come from config, normalize with .lower() before enum coercion.
Use the sql_only flag on the query engine for dry runs — it is not a query mode.

When it happens

Trigger: Passing as_query_engine(query_mode='SQL') — the enum comparison is case-sensitive because the member value is lowercase 'sql'; passing a misspelled or made-up mode name; passing SQLQueryMode.SQL_ONLY which is not handled here (sql_only is a separate flag on the query engine, not a mode).

Common situations: Case-mismatch bugs from uppercase config values; confusion between the sql_only=True convenience flag and a hypothetical query mode; newer devs assuming more modes exist because SQLQueryMode has other uses elsewhere.

Related errors

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