How to Fix 'prompt template error' in CrewAI (Python)

What the error means

prompt template error in CrewAI usually means the agent tried to render a prompt with missing or malformed variables. You’ll hit it when defining an Agent, Task, or custom prompt template and one of the placeholders does not match the inputs CrewAI has at runtime.

Most of the time this shows up during task execution, especially when you pass inputs={...} to crew.kickoff() or when a task description includes {placeholders} that are never provided.

The Most Common Cause

The #1 cause is a mismatch between placeholder names in your task prompt and the keys you pass at kickoff.

CrewAI uses string formatting under the hood. If your task says {company_name} but you pass {"company": "Acme"}, you’ll get a template rendering failure, often surfaced as something like:

• •ValueError: Missing input keys: {'company_name'}
• •prompt template error
• •KeyError: 'company_name'

Broken vs fixed pattern

# BROKEN
from crewai import Agent, Task, Crew, Process

researcher = Agent(
    role="Researcher",
    goal="Research the target company",
    backstory="You are good at company research."
)

task = Task(
    description="Research {company_name} and summarize its market position.",
    expected_output="A short company summary.",
    agent=researcher
)

crew = Crew(agents=[researcher], tasks=[task], process=Process.sequential)

# Wrong key: company instead of company_name
result = crew.kickoff(inputs={"company": "Acme Corp"})

# FIXED
from crewai import Agent, Task, Crew, Process

researcher = Agent(
    role="Researcher",
    goal="Research the target company",
    backstory="You are good at company research."
)

task = Task(
    description="Research {company_name} and summarize its market position.",
    expected_output="A short company summary.",
    agent=researcher
)

crew = Crew(agents=[researcher], tasks=[task], process=Process.sequential)

# Correct key matches placeholder exactly
result = crew.kickoff(inputs={"company_name": "Acme Corp"})

If you’re using multiple placeholders, every one of them must be present:

description = "Analyze {company_name} in {industry} and return 3 risks."

Then your kickoff must include both:

crew.kickoff(inputs={
    "company_name": "Acme Corp",
    "industry": "insurance"
})

Other Possible Causes

1. Missing curly braces or malformed template syntax

CrewAI expects placeholders in {name} format. If you use $name, %s, or broken braces, the formatter won’t resolve correctly.

# BROKEN
description = "Summarize company: {company_name"

# FIXED
description = "Summarize company: {company_name}"

2. Passing non-string values where a template expects text

If you build a prompt from a dict or list without converting it cleanly to text, the prompt renderer can fail or produce garbage output.

# BROKEN
task = Task(
    description={"text": "Review {policy_id}"},
    expected_output="Summary",
    agent=agent
)

# FIXED
task = Task(
    description="Review {policy_id}",
    expected_output="Summary",
    agent=agent
)

3. Using Python .format() too early

A common mistake is formatting the string before CrewAI sees it. If you call .format() yourself and leave unresolved placeholders behind, it can break later.

# BROKEN
template = "Analyze {company_name} for {risk_type}"
description = template.format(company_name="Acme")  # risk_type missing here

# FIXED
description = "Analyze {company_name} for {risk_type}"
crew.kickoff(inputs={
    "company_name": "Acme",
    "risk_type": "credit risk"
})

4. Variable names collide with internal prompt fields

If you use names that overlap with internal task/agent fields or reserved context values, debugging gets messy fast. Keep input keys explicit and domain-specific.

# Risky pattern
description = "Write a report about {input}"

# Better pattern
description = "Write a report about {report_topic}"

How to Debug It

1. •

   Print the exact task description before kickoff
   Confirm every {placeholder} in the final string.

   print(task.description)
   

2. •

   Compare placeholders against inputs keys
   Make sure names match exactly, including underscores and spelling.

   inputs = {"company_name": "Acme", "industry": "banking"}
   

3. •

   Reduce to one task and one variable
   Strip the crew down until the error disappears. This tells you whether the issue is in one task or in shared context.

4. •

   Check stack trace for formatter failures
   Look for messages like:

   • •KeyError
   • •ValueError: Missing input keys
   • •prompt template error
   • •failures inside task rendering or agent prompt construction

If you see the error during crew.kickoff(), it’s usually an input/template mismatch rather than an LLM problem.

Prevention

• •

  Keep placeholder names consistent across prompts, tasks, and kickoff inputs.

• •

  Validate required inputs before calling crew.kickoff().

  required = {"company_name", "industry"}
  missing = required - set(inputs.keys())
  if missing:
      raise ValueError(f"Missing inputs: {missing}")
  

• •

  Avoid mixing manual .format() calls with CrewAI-managed templates unless you fully control every placeholder.

• •

  Use small helper functions to build task descriptions so templates stay readable and testable.

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.