huggingface/smolagents · error · Exception

Error during jinja template rendering: {type(e).__name__}: {

Error message

Error during jinja template rendering: {type(e).__name__}: {e}

What it means

This error is raised when a Jinja2 prompt template fails to render. populate_template compiles the template with StrictUndefined, so any variable referenced in the template that is not supplied in the variables dict (or any malformed Jinja syntax) makes render() raise, and the exception is re-wrapped with its type name and message.

Source

Thrown at src/smolagents/agents.py:107

    AgentToolExecutionError,
    create_agent_gradio_app_template,
    extract_code_from_text,
    is_valid_name,
    make_init_file,
    parse_code_blobs,
    truncate_content,
)


logger = getLogger(__name__)


def populate_template(template: str, variables: dict[str, Any]) -> str:
    compiled_template = Template(template, undefined=StrictUndefined)
    try:
        return compiled_template.render(**variables)
    except Exception as e:
        raise Exception(f"Error during jinja template rendering: {type(e).__name__}: {e}")


@dataclass
class ActionOutput:
    output: Any
    is_final_answer: bool


@dataclass
class ToolOutput:
    id: str
    output: Any
    is_final_answer: bool
    observation: str
    tool_call: ToolCall


class PlanningPromptTemplate(TypedDict):

View on GitHub (pinned to 30bb116109)

Solutions

1. Inspect the exception message: it embeds the original Jinja2 error (e.g. UndefinedError: 'authorized_imports' is undefined), which names the missing variable
2. Ensure every {{ var }} in your custom prompt_templates is populated; either add the variable to the template's variables or remove it from the template
3. If your template should tolerate missing values, replace StrictUndefined behavior by using {{ var | default('') }} in the template
4. Check that dynamic strings (tool descriptions, names) injected into templates are escaped or free of stray {{ }} tokens

Example fix

# before
prompt_templates={"system_prompt": "Tools: {{ tools_list }}"}  # 'tools_list' undefined -> StrictUndefined error

# after
prompt_templates={"system_prompt": "Tools: {{ tool_descriptions | default('') }}"}

from jinja2 import Environment, StrictUndefined
env = Environment(undefined=StrictUndefined)
# dry-run your custom template with the variables smolagents provides
try:
    env.from_string(my_template).render(tool_descriptions="...", managed_agents="...", authorized_imports="...")
except Exception as e:
    print("template will fail:", e)

try:
    agent.run(task)
except Exception as e:
    if "jinja template rendering" in str(e):
        # inspect inner message for the undefined variable / syntax error
        log.error(e)

When it happens

Trigger: Calling initialize_system_prompt(), run(), provide_final_answer(), or _generate_planning_step() on an agent whose prompt_templates reference a variable (e.g. {{ authorized_imports }}, {{ tool_descriptions }}) that isn't provided; or passing a custom prompt_templates dict containing invalid Jinja2 syntax or a typo'd variable name.

Common situations: Customizing ManagedAgent or CodeAgent system prompts with a custom template that uses an undefined variable; upgrading smolagents versions where template variables were renamed/added; passing a tool whose description contains raw Jinja delimiters like {{ }}.

Related errors

• The variable `{name.id}` is not defined.
• Cannot specify both 'messages' and 'steps' parameters. Use '
• The 'system_prompt' property is read-only. Use 'self.prompt_
• Agent name '{name}' must be a valid Python identifier and no
• Each tool or managed_agent should have a unique name! You pa

AI-assisted analysis of huggingface/smolagents@30bb116109 (2026-08-28). Data as JSON: /api/errors/95010caeb8224f1a. Report an issue: GitHub.