sgl-project/sglang · error · RuntimeError

Chat template {chat_template_arg} is not a built-in template

Error message

Chat template {chat_template_arg} is not a built-in template name or a valid chat template file path.

What it means

When an explicit --chat-template argument is given, TemplateManager first tries builtin template names, then treats it as a file path. If neither matches, this RuntimeError reports the value is neither a builtin name nor an existing file.

Source

Thrown at python/sglang/srt/parser/template_manager.py:197

            if self._suggested_reasoning_parser:
                parts.append(f"reasoning_parser={self._suggested_reasoning_parser}")
            if self._suggested_tool_call_parser:
                parts.append(f"tool_call_parser={self._suggested_tool_call_parser}")
            if parts:
                logger.info(f"Auto-detected template features: {', '.join(parts)}")

    def _load_explicit_chat_template(
        self, tokenizer_manager: TokenizerManager, chat_template_arg: str
    ) -> None:
        """Load explicitly specified chat template."""
        logger.info(f"Loading chat template from argument: {chat_template_arg}")

        if chat_template_exists(chat_template_arg):
            self._chat_template_name = chat_template_arg
            return

        if not os.path.exists(chat_template_arg):
            raise RuntimeError(
                f"Chat template {chat_template_arg} is not a built-in template name "
                "or a valid chat template file path."
            )

        if chat_template_arg.endswith(".jinja"):
            self._load_jinja_template(tokenizer_manager, chat_template_arg)
        else:
            self._load_json_chat_template(chat_template_arg)

    def guess_chat_template_from_model_path(self, model_path: str) -> None:
        """
        Infer chat template name from model path.

        Args:
            model_path: Path to the model
        """
        template_name = get_conv_template_by_model_path(model_path)
        if template_name is not None:

View on GitHub (pinned to 0132848349)

Solutions

1. Verify the file exists with an absolute path: ls -l /full/path/to/template.jinja
2. Or use an exact builtin template name (check the registered names in sglang)
3. If in a container, ensure the template file is mounted/copied into the image

Example fix

# before
python -m sglang.launch_server --chat-template mytmpl
# after
python -m sglang.launch_server --chat-template /app/templates/mytmpl.jinja

import os
ok = chat_template_exists(arg) or os.path.isfile(os.path.abspath(arg))
if not ok:
    raise FileNotFoundError(f"template {arg!r} not found; use builtin name or absolute path")

def is_loadable_template(arg: str) -> TypeGuard[str]:
    import os
    from sglang.srt.parser.template_manager import chat_template_exists
    return chat_template_exists(arg) or os.path.isfile(arg)

try:
    tm.load_chat_template(chat_template_arg, tokenizer_manager)
except RuntimeError as e:
    if "not a built-in template name" in str(e):
        sys.exit(f"fix --chat-template path: {chat_template_arg}")
    raise

When it happens

Trigger: Launching the server with --chat-template my_template (not a registered builtin) where ./my_template also doesn't exist on disk; or a path with a typo/relative to wrong working directory.

Common situations: Typos in builtin template names, moved/renamed template files, relative paths resolved from a different CWD (e.g. running under systemd or Docker), or missing file in the container image.

Related errors

• Completion template {completion_template_arg} is not a built
• --default-chat-template-kwargs must decode to a JSON object
• metal shader source not found: {metal_src}
• MiniMax-H3 on MPS requires synchronous layerwise offload for
• MiniMax-H3 MPS execution does not support torch.compile; pas

AI-assisted analysis of sgl-project/sglang@0132848349 (2026-08-28). Data as JSON: /api/errors/044e5017e9da4c84. Report an issue: GitHub.