microsoft/graphrag · error · ValueError

Templates directory '{base_dir}' does not exist or is not a

Error message

Templates directory '{base_dir}' does not exist or is not a directory.

What it means

FileTemplateManager.__init__ raises this ValueError when base_dir does not exist on disk or is not a directory. The path is resolved with Path.resolve() and checked with exists()/is_dir() before the manager is usable, failing fast so template lookups never silently return nothing.

Source

Thrown at packages/graphrag-llm/graphrag_llm/templating/file_template_manager.py:51

                The file extension for template files.
            encoding: str (default="utf-8")
                The encoding used to read template files.

        Raises
        ------
            ValueError
                If the base directory does not exist or is not a directory.
                If the template_extension is an empty string.
        """
        self._templates = {}
        self._encoding = encoding

        self._templates_extension = template_extension

        self._templates_dir = Path(base_dir).resolve()
        if not self._templates_dir.exists() or not self._templates_dir.is_dir():
            msg = f"Templates directory '{base_dir}' does not exist or is not a directory."
            raise ValueError(msg)

    def get(self, template_name: str) -> str | None:
        """Retrieve a template by its name."""
        template_file = (
            self._templates_dir / f"{template_name}{self._templates_extension}"
        )
        if template_file.exists() and template_file.is_file():
            return template_file.read_text(encoding=self._encoding)
        return None

    def register(self, template_name: str, template: str) -> None:
        """Register a new template."""
        self._templates[template_name] = template
        template_path = (
            self._templates_dir / f"{template_name}{self._templates_extension}"
        )
        template_path.write_text(template, encoding=self._encoding)

View on GitHub (pinned to f40e9a26ce)

Solutions

Verify the path exists and is a directory (os.path.isdir) before constructing the manager
Use absolute paths or resolve paths relative to your package/module (__file__) instead of cwd
Create the templates directory or fix packaging so it ships with your app
If the path may be relative to cwd, resolve it explicitly before passing

Example fix

# before
mgr = FileTemplateManager(base_dir="templates")

# after
from pathlib import Path
base = Path(__file__).parent / "templates"
mgr = FileTemplateManager(base_dir=str(base))

Defensive patterns

Strategy: validation

Validate before calling

import os

if not os.path.isdir(base_dir):
    raise ValueError(f"Templates dir missing: {base_dir}")
mgr = FileTemplateManager(base_dir=base_dir)

Type guard

import os

def is_valid_templates_dir(p: str) -> bool:
    return os.path.isdir(p)

Try / catch

try:
    mgr = FileTemplateManager(base_dir=base_dir)
except ValueError as e:
    if "does not exist or is not a directory" in str(e):
        # create dir or point to a packaged path
        raise
    raise

Prevention

Resolve template paths relative to your module, not cwd
Verify the templates dir exists in deployment packaging (wheel/docker image)
Add a startup check for required asset directories

When it happens

Trigger: Constructing FileTemplateManager(base_dir=...) where base_dir points to a missing folder, a file instead of a directory, or a relative path that resolves against an unexpected working directory.

Common situations: Deployments where templates directory is not packaged/copied, wrong relative path assumptions (cwd changes between dev and prod), or passing a template file path instead of its directory.

Related errors

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