run-llama/llama_index · error · ValueError

Unknown SQL parser mode: {sql_parser_mode}

Error message

Unknown SQL parser mode: {sql_parser_mode}

What it means

SQLRetriever._load_sql_parser raises ValueError(f'Unknown SQL parser mode: {sql_parser_mode}') when the mode is neither SQLParserMode.DEFAULT nor SQLParserMode.PGVECTOR. The parser mode selects how raw LLM SQL output is cleaned/parsed before execution; only the plain default parser and the pgvector-aware parser (which rewrites embedding parameters) are registered. This runs inside SQLRetriever.__init__ (via Settings/constructor), so it fails at retriever construction, not at query time.

Source

Thrown at llama-index-core/llama_index/core/indices/struct_store/sql_retriever.py:274

    def _update_prompts(self, prompts: PromptDictType) -> None:
        """Update prompts."""
        if "text_to_sql_prompt" in prompts:
            self._text_to_sql_prompt = prompts["text_to_sql_prompt"]

    def _get_prompt_modules(self) -> PromptMixinType:
        """Get prompt modules."""
        return {}

    def _load_sql_parser(
        self, sql_parser_mode: SQLParserMode, embed_model: BaseEmbedding
    ) -> BaseSQLParser:
        """Load SQL parser."""
        if sql_parser_mode == SQLParserMode.DEFAULT:
            return DefaultSQLParser()
        elif sql_parser_mode == SQLParserMode.PGVECTOR:
            return PGVectorSQLParser(embed_model=embed_model)
        else:
            raise ValueError(f"Unknown SQL parser mode: {sql_parser_mode}")

    def _load_get_tables_fn(
        self,
        sql_database: SQLDatabase,
        tables: Optional[Union[List[str], List[Table]]] = None,
        context_query_kwargs: Optional[dict] = None,
        table_retriever: Optional[ObjectRetriever[SQLTableSchema]] = None,
    ) -> Callable[[str], List[SQLTableSchema]]:
        """Load get_tables function."""
        context_query_kwargs = context_query_kwargs or {}
        if table_retriever is not None:
            return lambda query_str: cast(Any, table_retriever).retrieve(query_str)
        else:
            if tables is not None:
                table_names: List[str] = [
                    t.name if isinstance(t, Table) else t for t in tables
                ]
            else:

View on GitHub (pinned to afd0fef371)

Solutions

1. Use the enum: from llama_index.core.indices.struct_store.sql_retriever import SQLParserMode; SQLRetriever(..., sql_parser_mode=SQLParserMode.DEFAULT).
2. If passing a string, use the exact enum value 'default' or 'pgvector'.
3. Omit sql_parser_mode entirely — DEFAULT is the default.

Example fix

# before
retriever = SQLRetriever(index, sql_parser_mode="plain")  # ValueError

# after
from llama_index.core.indices.struct_store.sql_retriever import SQLParserMode
retriever = SQLRetriever(index, sql_parser_mode=SQLParserMode.DEFAULT)

from llama_index.core.indices.struct_store.sql_retriever import SQLParserMode

VALID_PARSER_MODES = {SQLParserMode.DEFAULT, SQLParserMode.PGVECTOR}

def resolve_parser_mode(m) -> SQLParserMode:
    mode = SQLParserMode(m) if isinstance(m, str) else m
    if mode not in VALID_PARSER_MODES:
        raise ValueError(f"unsupported sql_parser_mode: {m}; use {VALID_PARSER_MODES}")
    return mode

from llama_index.core.indices.struct_store.sql_retriever import SQLParserMode

def is_valid_parser_mode(m) -> bool:
    try:
        return SQLParserMode(m) in (SQLParserMode.DEFAULT, SQLParserMode.PGVECTOR)
    except ValueError:
        return False

When it happens

Trigger: Calling SQLRetriever(..., sql_parser_mode='default_mode') or some guessed string; passing an enum member from a different class; passing SQLParserMode.PGVECTOR to a non-pgvector setup is fine, but any third value or bad string hits the else.

Common situations: String typos ('defaults', 'DEFAULT' where the enum value is lowercase); stale tutorial snippets naming modes that no longer exist; copy-pasting pgvector example config into the wrong parameter.

Related errors

• Not supported
• Unknown query mode: {query_mode}
• Unknown retriever mode: {retriever_mode}
• LLM must be a FunctionCallingLLM
• Unknown retriever mode: {retriever_mode}

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