{"record":{"id":"8dc9131ca83ec0c3","repo":"run-llama/llama_index","slug":"custom-prompt-must-have-the-following-template-var","errorCode":null,"errorMessage":"custom_prompt must have the following template variables: {default_prompt.template_vars}","messagePattern":"custom_prompt must have the following template variables: (.+?)","errorType":"validation","errorClass":"ValueError","httpStatus":null,"severity":"error","filePath":"llama-index-core/llama_index/core/indices/struct_store/sql_query.py","lineNumber":316,"sourceCode":"            dialect=self._sql_database.dialect,\n        )\n\n        sql_query_str = self._parse_response_to_sql(response_str)\n        # assume that it's a valid SQL query\n        logger.debug(f\"> Predicted SQL query: {sql_query_str}\")\n\n        response_str, metadata = self._run_with_sql_only_check(sql_query_str)\n        metadata[\"sql_query\"] = sql_query_str\n        return Response(response=response_str, metadata=metadata)\n\n\ndef _validate_prompt(\n    custom_prompt: BasePromptTemplate,\n    default_prompt: BasePromptTemplate,\n) -> None:\n    \"\"\"Validate prompt.\"\"\"\n    if custom_prompt.template_vars != default_prompt.template_vars:\n        raise ValueError(\n            \"custom_prompt must have the following template variables: \"\n            f\"{default_prompt.template_vars}\"\n        )\n\n\nclass BaseSQLTableQueryEngine(BaseQueryEngine):\n    \"\"\"\n    Base SQL Table query engine.\n\n    NOTE: Any Text-to-SQL application should be aware that executing\n    arbitrary SQL queries can be a security risk. It is recommended to\n    take precautions as needed, such as using restricted roles, read-only\n    databases, sandboxing, etc.\n    \"\"\"\n\n    def __init__(\n        self,\n        llm: Optional[LLM] = None,","sourceCodeStart":298,"sourceCodeEnd":334,"githubUrl":"https://github.com/run-llama/llama_index/blob/afd0fef371831f9bda13e5af7167cf4e981278ab/llama-index-core/llama_index/core/indices/struct_store/sql_query.py#L298-L334","documentation":"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.","triggerScenarios":"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.","commonSituations":"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.","solutions":["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.","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.","If you genuinely need extra variables, use a partial prompt or wrap formatting yourself instead of custom_prompt."],"exampleFix":"# before\ncustom = PromptTemplate(\"Translate to SQL: {query}\")\nengine = index.as_query_engine(custom_prompt=custom)  # ValueError\n\n# after\nfrom llama_index.core.prompts import PromptTemplate\ncustom = PromptTemplate(\n    \"You are a SQL expert. Given {dialect} schema:\\n{schema}\\nWrite SQL for: {query_str}\"\n)\nengine = index.as_query_engine(custom_prompt=custom)","handlingStrategy":"validation","validationCode":"from llama_index.core.prompts import PromptTemplate\n\ndef assert_prompt_vars_match(custom: PromptTemplate, default: PromptTemplate) -> None:\n    if set(custom.template_vars) != set(default.template_vars):\n        raise ValueError(\n            f\"custom_prompt vars {custom.template_vars} != required {default.template_vars}\"\n        )","typeGuard":"def prompt_vars_match(custom, default) -> bool:\n    return set(custom.template_vars) == set(default.template_vars)","tryCatchPattern":null,"preventionTips":["Derive custom prompts from the shipped default template (copy its string, edit prose only).","Keep all {query_str}, {schema}, {dialect} placeholders untouched in SQL prompts.","After upgrading llama-index, re-check the default prompt's template_vars — it can change between versions."],"tags":["sql","prompt-template","validation","llama-index"],"backgroundTag":null,"analyzedSha":"afd0fef371831f9bda13e5af7167cf4e981278ab","analyzedAt":"2026-08-15T05:42:58.429Z","schemaVersion":2},"datasetVersion":"2026-08-15T22:17:37.221Z"}