vllm-project/vllm · error · TemplateError

failed to read chat template file

Error message

failed to read chat template file

What it means

The HF renderer detected the configured chat template value is a filesystem path and tried to read it (`renderer/hf/template.rs:59`), but `fs::read_to_string` returned an I/O error (captured as `#[source]`). Distinct from error 33, which is thrown when the path does not exist at all — this wraps lower-level failures like permission denied or I/O faults.

Source

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

// 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. Check the chained `std::io::Error` kind: PermissionDenied → fix file ownership/permissions (chmod 644, chown the service user).
2. Confirm the path is a regular file and the full directory chain is traversable by the server user.
3. If on a network mount, verify the mount is healthy and re-deploy.
4. Prefer bundling the template inside the image/config rather than referencing host paths.

Example fix

# before
ls -l /etc/vllm/template.jinja
# -rw------- 1 root root ... ; server runs as vllm

# after
chown vllm:vllm /etc/vllm/template.jinja && chmod 644 /etc/vllm/template.jinja

let path = std::path::Path::new(&template_path);
let meta = std::fs::metadata(path)?;
if !meta.is_file() { return Err("chat template path is not a regular file"); }

match result {
    Err(TemplateError::ReadTemplateFile(io_err)) => {
        eprintln!("cannot read chat template: {io_err}; check permissions and mount");
        std::process::exit(2);
    }
    other => other?,
}

When it happens

Trigger: Setting `--chat-template /path/to/template.jinja` where the file exists but the server process lacks read permission, the path is a directory, or reading fails mid-way (disk/NFS error).

Common situations: Containerized vLLM running as non-root against a file owned by root with 0600; Kubernetes volume mount issues; trailing-slash paths pointing at directories; race where the file is deleted after the existence check.

Related errors

• chat template looks like a file path but does not exist
• {kind} parser `{name}` is not registered{}
• gpt_oss uses native Harmony output parsing; generic {kind} p
• failed to render jinja template
• failed to parse chat_template.json

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