How to Fix 'prompt template error during development' in LlamaIndex (Python)

The error usually means LlamaIndex tried to render a prompt template and failed before the LLM call even started. You’ll see it during development when you pass the wrong prompt object, use a template with missing variables, or mix old and new LlamaIndex APIs.

The key thing: this is almost always a prompt construction bug, not an LLM provider issue. The stack trace often points at PromptTemplate, ChatPromptTemplate, BasePromptTemplate, or a component like RetrieverQueryEngine or QuestionAnswerPrompt.

The Most Common Cause

The #1 cause is passing variables that do not match the template placeholders.

In LlamaIndex, prompt templates are strict. If your template expects {context_str} and {query_str}, but you pass only one of them, you’ll get an error like:

• •ValueError: Missing variables for prompt template: {'query_str'}
• •KeyError: 'context_str'
• •ValueError: Prompt template error during development

Here’s the broken pattern versus the fixed pattern.

# BROKEN
from llama_index.core import PromptTemplate

template = PromptTemplate(
    "Context: {context_str}\nQuestion: {query_str}\nAnswer:"
)

# Missing query_str
rendered = template.format(context_str="Some context")

# FIXED
from llama_index.core import PromptTemplate

template = PromptTemplate(
    "Context: {context_str}\nQuestion: {query_str}\nAnswer:"
)

rendered = template.format(
    context_str="Some context",
    query_str="What does this mean?"
)
print(rendered)

If you’re wiring this into a query engine, the same rule applies. For example, ResponseSynthesizer, RetrieverQueryEngine, and custom PromptHelper flows all expect the right variable names.

# BROKEN
query_engine = index.as_query_engine(text_qa_template=template)
response = query_engine.query("What is in the document?")
# If template placeholders don't match what LlamaIndex supplies, rendering fails.

# FIXED
from llama_index.core import PromptTemplate

text_qa_template = PromptTemplate(
    "Context information is below.\n"
    "---------------------\n"
    "{context_str}\n"
    "---------------------\n"
    "Given the context, answer: {query_str}\n"
)

query_engine = index.as_query_engine(text_qa_template=text_qa_template)
response = query_engine.query("What is in the document?")

Other Possible Causes

1) Using a chat prompt where a text prompt is expected

A common mistake is swapping ChatPromptTemplate and PromptTemplate. Some components expect plain text formatting, not chat messages.

# BROKEN
from llama_index.core.prompts import ChatPromptTemplate

chat_prompt = ChatPromptTemplate.from_messages([
    ("system", "Use the context."),
    ("user", "{query_str}")
])

# This may fail if the component expects a text-style prompt.

# FIXED
from llama_index.core import PromptTemplate

text_prompt = PromptTemplate(
    "Use the context below.\n{context_str}\n\nQuestion: {query_str}"
)

2) Old API names from older LlamaIndex versions

LlamaIndex changed a lot across versions. Code that used ServiceContext, old import paths, or deprecated prompt classes can trigger confusing template errors.

# BROKEN (older style may break on newer versions)
from llama_index import ServiceContext
from llama_index.prompts.base import PromptTemplate

# FIXED (current style)
from llama_index.core import Settings, PromptTemplate

If your code was copied from an old blog post or GitHub gist, check version compatibility first.

3) Passing extra keys into .format() or .partial_format()

Sometimes the failure is not missing variables, but bad input shape. If your template does not define a variable, don’t pass it as if it exists.

# BROKEN
template = PromptTemplate("Answer using {context_str}")
template.format(context_str="abc", query_str="extra value")

# FIXED
template = PromptTemplate("Answer using {context_str}")
template.format(context_str="abc")

4) Custom prompt function returns malformed output

If you build prompts dynamically, your function might return a string with unresolved placeholders like {foo} or invalid formatting syntax.

# BROKEN
def build_prompt(topic: str):
    return f"Summarize {topic} using {missing_var}"

prompt = build_prompt("payments")

# FIXED
def build_prompt(topic: str):
    return f"Summarize {topic} using clear evidence from the provided context."

prompt = build_prompt("payments")

How to Debug It

1. •

   Read the exact missing variable name

   • •If the stack trace says Missing variables for prompt template: {'query_str'}, that’s your answer.
   • •Compare that set against your template placeholders.
2. •

   Print the template before it reaches LlamaIndex

   • •Look for unresolved braces like {context}, {question}, or accidental double braces.
   • •Also check whether you’re using chat-style messages in a text-only path.
3. •

   Inspect the component expecting the prompt

   • •Common places:
     • •index.as_query_engine(...)
     • •RetrieverQueryEngine
     • •ResponseSynthesizer
     • •custom retrievers or rerankers
   • •Each one has different expectations for variable names.
4. •

   Reduce to a minimal repro

   • •Remove everything except:
     • •one document
     • •one prompt template
     • •one query call
   • •If it works there, your bug is in surrounding glue code or version mismatch.

Prevention

• •Keep prompt variable names explicit and consistent across templates and callers.
• •Pin your LlamaIndex version and check migration notes before upgrading.
• •Add a small unit test that formats every custom prompt with sample inputs.

A simple test catches most of these failures before they hit runtime:

def test_prompt_formats():
    from llama_index.core import PromptTemplate

    tmpl = PromptTemplate("Context: {context_str}\nQ: {query_str}")
    out = tmpl.format(context_str="doc text", query_str="what happened?")
    assert "doc text" in out

If you see prompt template error during development in LlamaIndex, start with variable matching first. In practice, that fixes most cases faster than chasing provider configs or embedding settings.

Keep learning

• •The complete AI Agents Roadmap — my full 8-step breakdown
• •Free: The AI Agent Starter Kit — PDF checklist + starter code
• •Work with me — I build AI for banks and insurance companies

By Cyprian Aarons, AI Consultant at Topiax.