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

corrupt existing generation {destination}: {error}

Error message

corrupt existing generation {destination}: {error}

What it means

When the destination generation directory already exists, _verify_existing reads manifest.json. If that file is missing/unreadable (OSError), not valid UTF-8 (UnicodeError), or not valid JSON (JSONDecodeError), the generation is treated as corrupt and rendering aborts rather than silently overwriting.

Source

Thrown at src/scripts/render_skill.py:275

            raise RenderError(f"unsupported render token: {token}")
        target = snapshot.group(1)
        if target not in source_names:
            raise RenderError(f"snapshot reference targets undeclared source: {target}")
        return str(destination / target)

    rendered: dict[str, str] = {}
    for name, content in sources.items():
        # Inserted paths and customization prose are never scanned as source tokens.
        rendered[name] = token_pattern.sub(replace, content)
    return rendered


def _verify_existing(destination: Path, manifest: dict[str, Any]) -> None:
    manifest_path = destination / "manifest.json"
    try:
        existing = json.loads(manifest_path.read_text(encoding="utf-8"))
    except (OSError, UnicodeError, json.JSONDecodeError) as error:
        raise RenderError(f"corrupt existing generation {destination}: {error}") from error
    if existing != manifest:
        raise RenderError(f"generation collision or corruption at {destination}")
    expected_files = set(manifest["outputs"]) | {"manifest.json"}
    actual_files = {
        path.relative_to(destination).as_posix()
        for path in destination.rglob("*")
        if path.is_file()
    }
    if actual_files != expected_files:
        raise RenderError(f"generation contains unexpected or missing files: {destination}")
    for name, expected_hash in manifest["outputs"].items():
        try:
            actual_hash = _hash_bytes((destination / name).read_bytes())
        except OSError as error:
            raise RenderError(f"failed to verify {destination / name}: {error}") from error
        if actual_hash != expected_hash:
            raise RenderError(f"generation output hash mismatch: {destination / name}")

View on GitHub (pinned to b70486b9bd)

Solutions

1. Delete the corrupt generation directory and re-run render to regenerate it cleanly.
2. If generations are committed to VCS, restore manifest.json from version control.
3. Avoid manually editing files inside generated output directories.

Example fix

# before: manifest.json missing or corrupt
# after
rm -rf _bmad/render/<skill>/<slug>-<hash>
python src/scripts/render_skill.py --project-root . --skill skills/my-skill

import json
from pathlib import Path

def manifest_ok(dest: Path) -> bool:
    m = dest / "manifest.json"
    try:
        json.loads(m.read_text(encoding="utf-8"))
        return True
    except (OSError, UnicodeError, json.JSONDecodeError):
        return False

from render_skill import render, RenderError

try:
    entry = render(project_root, skill_dir)
except RenderError as e:
    if "corrupt existing generation" in str(e):
        # remove the corrupt generation dir and re-run
        ...
    raise

When it happens

Trigger: Re-running render into the same destination hash directory where manifest.json was deleted, truncated, or contains invalid JSON (e.g. hand-edited and broken).

Common situations: Manual editing/deletion of generated directories; partial writes from a previously crashed run; hand-editing the manifest.

Related errors

• generation collision or corruption at {destination}
• generation contains unexpected or missing files: {destinatio
• failed to verify {destination / name}: {error}
• generation output hash mismatch: {destination / name}
• render source escapes skill directory: {name}

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