run-llama/llama_index · error · ValueError

custom_prompt must have the following template variables: {d

Error message

custom_prompt must have the following template variables: {default_prompt.template_vars}

What it means

as_query_engine(custom_prompt=...) on the SQL index calls _validate_prompt, which raises ValueError when custom_prompt.template_vars != default_prompt.template_vars. The text-to-SQL prompt must expose exactly the variables the engine formats into it (the default TEXT_TO_SQL template's vars, e.g. query_str, schema, dialect); the equality check is on the full ordered list, so extra, missing, or reordered variables all fail. This protects the engine from a KeyError at format time later.

Source

Thrown at llama-index-core/llama_index/core/indices/struct_store/sql_query.py:316

            dialect=self._sql_database.dialect,
        )

        sql_query_str = self._parse_response_to_sql(response_str)
        # assume that it's a valid SQL query
        logger.debug(f"> Predicted SQL query: {sql_query_str}")

        response_str, metadata = self._run_with_sql_only_check(sql_query_str)
        metadata["sql_query"] = sql_query_str
        return Response(response=response_str, metadata=metadata)


def _validate_prompt(
    custom_prompt: BasePromptTemplate,
    default_prompt: BasePromptTemplate,
) -> None:
    """Validate prompt."""
    if custom_prompt.template_vars != default_prompt.template_vars:
        raise ValueError(
            "custom_prompt must have the following template variables: "
            f"{default_prompt.template_vars}"
        )


class BaseSQLTableQueryEngine(BaseQueryEngine):
    """
    Base SQL Table query engine.

    NOTE: Any Text-to-SQL application should be aware that executing
    arbitrary SQL queries can be a security risk. It is recommended to
    take precautions as needed, such as using restricted roles, read-only
    databases, sandboxing, etc.
    """

    def __init__(
        self,
        llm: Optional[LLM] = None,

View on GitHub (pinned to afd0fef371)

Solutions

1. Start from the default prompt and change only the prose: from llama_index.core.prompts.default_prompts import TEXT_TO_SQL_PROMPT; copy its template and keep {query_str}, {schema}, {dialect} placeholders intact.
2. Before passing, assert set(custom_prompt.template_vars) matches — read index.as_query_engine's default via retriever.get_prompts() or the module constant — and fix the mismatch the error message names.
3. If you genuinely need extra variables, use a partial prompt or wrap formatting yourself instead of custom_prompt.

Example fix

# before
custom = PromptTemplate("Translate to SQL: {query}")
engine = index.as_query_engine(custom_prompt=custom)  # ValueError

# after
from llama_index.core.prompts import PromptTemplate
custom = PromptTemplate(
    "You are a SQL expert. Given {dialect} schema:\n{schema}\nWrite SQL for: {query_str}"
)
engine = index.as_query_engine(custom_prompt=custom)

from llama_index.core.prompts import PromptTemplate

def assert_prompt_vars_match(custom: PromptTemplate, default: PromptTemplate) -> None:
    if set(custom.template_vars) != set(default.template_vars):
        raise ValueError(
            f"custom_prompt vars {custom.template_vars} != required {default.template_vars}"
        )

def prompt_vars_match(custom, default) -> bool:
    return set(custom.template_vars) == set(default.template_vars)

When it happens

Trigger: Passing a custom prompt template like 'Generate SQL for: {query}' that lacks {schema}/{dialect}; adding a new variable ({tone}) to a copied prompt; changing the wording but accidentally renaming a placeholder.

Common situations: Prompt-engineering iterations where the developer edits a copied template string and drops variables they consider unused; using a prompt written for a different llama-index version whose default template_vars changed after an upgrade.

Related errors

• Max iterations of {max_iterations} reached! Either something
• Handoff prompt must contain {agent_info}
• Handoff output prompt must contain {to_agent} and {reason}
• State prompt must contain {state} and {msg}
• CitableBlock content must contain exactly one block when pro

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