vllm-project/vllm · error · TemplateError

failed to render jinja template

Error message

failed to render jinja template

What it means

HF chat renderer error: executing the model's Jinja chat template with minijinja failed; the minijinja error is attached via `#[from]`. This happens at prompt-rendering time, after the template was successfully loaded — the failure is in evaluating it against your messages.

Source

Thrown at rust/src/chat/src/renderer/hf/error.rs:8

// SPDX-License-Identifier: Apache-2.0
// SPDX-FileCopyrightText: Copyright contributors to the vLLM project

use thiserror::Error as ThisError;

#[derive(Debug, ThisError)]
pub(crate) enum TemplateError {
    #[error("failed to render jinja template")]
    Jinja(#[from] minijinja::Error),
    #[error("failed to read chat template file")]
    ReadTemplateFile(#[source] std::io::Error),
    #[error("chat template looks like a file path but does not exist")]
    MissingTemplatePath,
    #[error("failed to parse chat_template.json")]
    ParseTemplateJson(#[source] serde_json::Error),
    #[error("chat_template.json does not contain a valid template")]
    InvalidTemplateJson,
}

View on GitHub (pinned to c794754062)

Solutions

1. Read the chained minijinja error — it names the undefined variable/filter and template line.
2. Remove or adapt the message type that triggers the failure (e.g. drop tools, convert array content to text).
3. Override the chat template with a compatible/simplified one via the renderer's template-override config.
4. Update the Rust chat crate if a newer version added support for the missing filter/feature.

Example fix

// before
messages: vec![ChatMessage::user(Content::parts([...]))] // template does `message['content'].strip()`

// after
messages: vec![ChatMessage::user("plain text")] // or override template that handles parts

match render_result {
    Err(e) if e.to_string().contains("failed to render jinja template") => {
        // inspect e.source() chain: undefined variable/filter + template line
        respond_bad_request("messages incompatible with this model's chat template")
    }
    other => other?,
}

When it happens

Trigger: Rendering a chat request where the template references a variable/filter the renderer did not provide (e.g. `tools`, `documents`, custom filters like `strftime_now`), or message content of a type the template does not handle (array content against a template expecting a string).

Common situations: Templates from newer transformers versions using filters/features minijinja does not implement; sending `tools` to a template that never expected them; sending multimodal content blocks to a text-only template; tool messages with a template lacking tool-role support.

Related errors

• failed to read chat template file
• chat template looks like a file path but does not exist
• failed to parse chat_template.json
• chat_template.json does not contain a valid template
• {kind} parser `{name}` is not registered{}

AI-assisted analysis of vllm-project/vllm@c794754062 (2026-08-14). Data as JSON: /api/errors/3b315d6e6e4cc0cf. Report an issue: GitHub.