microsoft/graphrag · error · ValueError

template_extension cannot be an empty string for file-based

Error message

template_extension cannot be an empty string for file-based template managers.

What it means

TemplateEngineConfig validation rejects template_extension values that are set but blank (empty or whitespace-only) for file-based template managers, since the manager could not match any template files.

Source

Thrown at packages/graphrag-llm/graphrag_llm/config/template_engine_config.py:56

    )

    encoding: str | None = Field(
        default=None,
        description="The file encoding for reading templates in file-based template managers.",
    )

    def _validate_file_template_manager_config(self) -> None:
        """Validate parameters for file-based template managers."""
        if self.base_dir is not None and self.base_dir.strip() == "":
            msg = "base_dir must be specified for file-based template managers."
            raise ValueError(msg)

        if (
            self.template_extension is not None
            and self.template_extension.strip() == ""
        ):
            msg = "template_extension cannot be an empty string for file-based template managers."
            raise ValueError(msg)

        if (
            self.template_extension is not None
            and not self.template_extension.startswith(".")
        ):
            self.template_extension = f".{self.template_extension}"

    @model_validator(mode="after")
    def _validate_model(self):
        """Validate the template engine configuration based on its type."""
        if self.template_manager == TemplateManagerType.File:
            self._validate_file_template_manager_config()
        return self

View on GitHub (pinned to f40e9a26ce)

Solutions

1. Set template_extension to a real extension such as ".j2" or "txt" (a leading dot is auto-added)
2. If you want no extension filter, omit template_extension entirely (leave it None)

Example fix

# before
TemplateEngineConfig(type=<file manager>, base_dir="prompts", template_extension="")
# after
TemplateEngineConfig(type=<file manager>, base_dir="prompts", template_extension=".j2")

ext = tmpl_cfg.get("template_extension")
if ext is not None and not ext.strip():
    tmpl_cfg.pop("template_extension")  # or fail loudly

When it happens

Trigger: TemplateEngineConfig(template_extension="" or " ") with a file-based manager type in settings.yaml.

Common situations: YAML key present with empty value; templated config rendering to blank; attempting to disable the extension filter by passing an empty string.

Understand the failure class

Background: "Invalid value" and "allowed values are" config errors: what your library rejected and how to fix it — this error's family across 41 libraries.

Related errors

• base_dir must be specified for file-based template managers.
• api_base must be specified with the 'azure' model provider.
• azure_deployment_name should not be specified for non-Azure
• api_key should not be set when using Azure Managed Identity.
• api_key must be set when auth_method=api_key.

AI-assisted analysis of microsoft/graphrag@f40e9a26ce (2026-08-27). Data as JSON: /api/errors/659f79d7b0cf9d79. Report an issue: GitHub.