{"record":{"id":"63c614f1980d8426","repo":"run-llama/llama_index","slug":"unknown-query-mode-query-mode-63c614","errorCode":null,"errorMessage":"Unknown query mode: {query_mode}","messagePattern":"Unknown query mode: (.+?)","errorType":"validation","errorClass":"ValueError","httpStatus":null,"severity":"error","filePath":"llama-index-core/llama_index/core/indices/struct_store/sql.py","lineNumber":165,"sourceCode":"\n    def as_query_engine(\n        self,\n        llm: Optional[LLMType] = None,\n        query_mode: Union[str, SQLQueryMode] = SQLQueryMode.NL,\n        **kwargs: Any,\n    ) -> BaseQueryEngine:\n        # NOTE: lazy import\n        from llama_index.core.indices.struct_store.sql_query import (\n            NLStructStoreQueryEngine,\n            SQLStructStoreQueryEngine,\n        )\n\n        if query_mode == SQLQueryMode.NL:\n            return NLStructStoreQueryEngine(self, **kwargs)\n        elif query_mode == SQLQueryMode.SQL:\n            return SQLStructStoreQueryEngine(self, **kwargs)\n        else:\n            raise ValueError(f\"Unknown query mode: {query_mode}\")\n\n\nGPTSQLStructStoreIndex = SQLStructStoreIndex\n","sourceCodeStart":147,"sourceCodeEnd":169,"githubUrl":"https://github.com/run-llama/llama_index/blob/afd0fef371831f9bda13e5af7167cf4e981278ab/llama-index-core/llama_index/core/indices/struct_store/sql.py#L147-L169","documentation":"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.","triggerScenarios":"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).","commonSituations":"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.","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."],"exampleFix":"# before\nengine = index.as_query_engine(query_mode=\"SQL\")  # ValueError\n\n# after\nfrom llama_index.core.indices.struct_store.sql_query import SQLQueryMode\nengine = index.as_query_engine(query_mode=SQLQueryMode.SQL)","handlingStrategy":"type-guard","validationCode":"from llama_index.core.indices.struct_store.sql_query import SQLQueryMode\n\nVALID_SQL_QUERY_MODES = {SQLQueryMode.NL, SQLQueryMode.SQL}\n\ndef safe_as_query_engine(index, query_mode=SQLQueryMode.NL, **kw):\n    if isinstance(query_mode, str):\n        query_mode = SQLQueryMode(query_mode)  # raises early with a clear message\n    assert query_mode in VALID_SQL_QUERY_MODES\n    return index.as_query_engine(query_mode=query_mode, **kw)","typeGuard":"from llama_index.core.indices.struct_store.sql_query import SQLQueryMode\n\ndef is_valid_sql_query_mode(m) -> bool:\n    try:\n        return SQLQueryMode(m) in (SQLQueryMode.NL, SQLQueryMode.SQL)\n    except ValueError:\n        return False","tryCatchPattern":null,"preventionTips":["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."],"tags":["sql","enum","api-misuse","llama-index"],"backgroundTag":null,"analyzedSha":"afd0fef371831f9bda13e5af7167cf4e981278ab","analyzedAt":"2026-08-15T05:42:58.429Z","schemaVersion":2},"datasetVersion":"2026-08-15T22:17:37.221Z"}