bmad-code-org/BMAD-METHOD · error · RenderError

project root does not contain _bmad/: {project_root}

Error message

project root does not contain _bmad/: {project_root}

What it means

render() requires the project root to contain a _bmad/ directory: it is where central config is loaded from and where the rendered snapshot is written (_bmad/render/...). Passing a project root without _bmad/ aborts immediately, before any source loading.

Source

Thrown at src/scripts/render_skill.py:326

            + b"\n"
        )
        try:
            os.rename(staging, destination)
        except OSError:
            if destination.exists():
                _verify_existing(destination, manifest)
            else:
                raise
    finally:
        if staging.exists():
            shutil.rmtree(staging, ignore_errors=True)


def render(project_root: Path, skill_dir: Path) -> Path:
    project_root = project_root.resolve(strict=True)
    skill_dir = skill_dir.resolve(strict=True)
    if not (project_root / "_bmad").is_dir():
        raise RenderError(f"project root does not contain _bmad/: {project_root}")

    sources = _load_sources(skill_dir)
    central = load_central_config(project_root)
    has_customization = any(
        _CUSTOM_TOKEN.search(content) for content in sources.values()
    )
    defaults = (
        load_toml(skill_dir / "customize.toml", required=True)
        if has_customization
        else None
    )
    customization = (
        load_customization(project_root, skill_dir) if has_customization else {}
    )
    replacements, input_values = _resolve_replacements(
        sources, central, customization, defaults, project_root
    )
    source_hashes = {

View on GitHub (pinned to b70486b9bd)

Solutions

1. Run BMAD initialisation so _bmad/ exists, or pass the correct repository root that already contains it.
2. Verify the path: ls "$PROJECT_ROOT/_bmad".
3. If _bmad was renamed/moved, restore it or update --project-root accordingly.

Example fix

# before
python src/scripts/render_skill.py --project-root ./src --skill skills/my-skill

# after (repo root that contains _bmad/)
python src/scripts/render_skill.py --project-root . --skill skills/my-skill

from pathlib import Path

def assert_bmad_root(project_root: Path) -> None:
    if not (project_root / "_bmad").is_dir():
        raise SystemExit(f"not a BMAD project root (no _bmad/): {project_root}")

When it happens

Trigger: Running the renderer with --project-root pointing at a directory that has not been initialised by BMAD (no _bmad/ folder), or a typo/wrong path such as a subdirectory instead of the repo root.

Common situations: Wrong current working directory; BMAD init not yet run; pointing at a subpackage instead of the repo root.

Related errors

• keyed array identifier `{candidate}` must not be empty
• {label} must be a string, got {type(value).__name__}
• {label} must not be empty
• {label} must be a list, got {type(value).__name__}
• {label} must be a list of tables

AI-assisted analysis of bmad-code-org/BMAD-METHOD@b70486b9bd (2026-08-13). Data as JSON: /api/errors/1f63a4c26617ad95. Report an issue: GitHub.