microsoft/graphrag · error · ValueError

base_dir must be specified for file-based template managers.

Error message

base_dir must be specified for file-based template managers.

What it means

TemplateEngineConfig validation rejects a base_dir that is set but whitespace-only for file-based template managers. The field must be a real directory path, not an empty/blank string.

Source

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

        default=None,
        description="The base directory for file-based template managers.",
    )

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

    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:

View on GitHub (pinned to f40e9a26ce)

Solutions

Set base_dir to an existing directory path containing your templates, e.g. base_dir: "prompts"
If using inline/in-memory templates, switch to the non-file template manager type so base_dir is not validated

Example fix

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

Defensive patterns

Strategy: validation

Validate before calling

bd = tmpl_cfg.get("base_dir")
if using_file_manager and (bd is None or not bd.strip()):
    raise ValueError("base_dir must be a non-empty path for file template managers")

Prevention

Point base_dir at a directory checked into the repo and verify with Path(bd).is_dir() at startup
Prefer inline template managers for tests

When it happens

Trigger: TemplateEngineConfig with base_dir="" or base_dir=" " while using a file-based template manager type (e.g. filesystem manager).

Common situations: YAML settings with an empty base_dir: value; template strings passed in base_dir by mistake; whitespace from templating/jinja rendering of the config.

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

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