Skip to content
🤖 Consolidated, AI-optimized BMAD docs: llms-full.txt. Fetch this plain text file for complete context.
BMAD Logo BMAD Method

BMGD Troubleshooting

Common issues and solutions when using BMGD workflows.

Installation Issues

Section titled “Installation Issues”

BMGD module not appearing

Section titled “BMGD module not appearing”

Symptom: BMGD agents and workflows are not available after installation.

Solutions:

  1. Verify BMGD was selected during installation
  2. Check _bmad/bmgd/ folder exists in your project
  3. Re-run installer with --add-module bmgd

Config file missing

Section titled “Config file missing”

Symptom: Workflows fail with “config not found” errors.

Solution: Check for _bmad/bmgd/config.yaml in your project. If missing, create it:

output_folder: '{project-root}/docs/game-design'
user_name: 'Your Name'
communication_language: 'English'
document_output_language: 'English'
game_dev_experience: 'intermediate'

Workflow Issues

Section titled “Workflow Issues”

”GDD not found” in Narrative workflow

Section titled “”GDD not found” in Narrative workflow”

Symptom: Narrative workflow can’t find the GDD.

Solutions:

  1. Ensure GDD exists in {output_folder}
  2. Check GDD filename contains “gdd” (e.g., game-gdd.md, my-gdd.md)
  3. If using sharded GDD, verify {output_folder}/gdd/index.md exists

Workflow state not persisting

Section titled “Workflow state not persisting”

Symptom: Returning to a workflow starts from the beginning.

Solutions:

  1. Check the output document’s frontmatter for stepsCompleted array
  2. Ensure document was saved before ending session
  3. Use “Continue existing” option when re-entering workflow

Wrong game type sections in GDD

Section titled “Wrong game type sections in GDD”

Symptom: GDD includes irrelevant sections for your game type.

Solutions:

  1. Review game type selection at Step 7 of GDD workflow
  2. You can select multiple types for hybrid games
  3. Irrelevant sections can be marked N/A or removed

Agent Issues

Section titled “Agent Issues”

Agent not recognizing commands

Section titled “Agent not recognizing commands”

Symptom: Typing a command like create-gdd doesn’t trigger the workflow.

Solutions:

  1. Ensure you’re chatting with the correct agent (Game Designer for GDD)
  2. Check exact command spelling (case-sensitive)
  3. Try workflow-status to verify agent is loaded correctly

Agent using wrong persona

Section titled “Agent using wrong persona”

Symptom: Agent responses don’t match expected personality.

Solutions:

  1. Verify correct agent file is loaded
  2. Check _bmad/bmgd/agents/ for agent definitions
  3. Start a fresh chat session with the correct agent

Document Issues

Section titled “Document Issues”

Document too large for context

Section titled “Document too large for context”

Symptom: AI can’t process the entire GDD or narrative document.

Solutions:

  1. Use sharded document structure (index.md + section files)
  2. Request specific sections rather than full document
  3. GDD workflow supports automatic sharding for large documents

Template placeholders not replaced

Section titled “Template placeholders not replaced”

Symptom: Output contains {{placeholder}} text.

Solutions:

  1. Workflow may have been interrupted before completion
  2. Re-run the specific step that generates that section
  3. Manually edit the document to fill in missing values

Frontmatter parsing errors

Section titled “Frontmatter parsing errors”

Symptom: YAML errors when loading documents.

Solutions:

  1. Validate YAML syntax (proper indentation, quotes around special characters)
  2. Check for tabs vs spaces (YAML requires spaces)
  3. Ensure frontmatter is bounded by --- markers

Phase 4 (Production) Issues

Section titled “Phase 4 (Production) Issues”

Sprint status not updating

Section titled “Sprint status not updating”

Symptom: Story status changes don’t reflect in sprint-status.yaml.

Solutions:

  1. Run sprint-planning to refresh status
  2. Check file permissions on sprint-status.yaml
  3. Verify workflow-install files exist in _bmad/bmgd/workflows/4-production/

Story context missing code references

Section titled “Story context missing code references”

Symptom: Generated story context doesn’t include relevant code.

Solutions:

  1. Ensure project-context.md exists and is current
  2. Check that architecture document references correct file paths
  3. Story may need more specific file references in acceptance criteria

Code review not finding issues

Section titled “Code review not finding issues”

Symptom: Code review passes but bugs exist.

Solutions:

  1. Code review is AI-assisted, not comprehensive testing
  2. Always run actual tests before marking story done
  3. Consider manual review for critical code paths

Performance Issues

Section titled “Performance Issues”

Workflows running slowly

Section titled “Workflows running slowly”

Symptom: Long wait times between workflow steps.

Solutions:

  1. Use IDE-based workflows (faster than web)
  2. Keep documents concise (avoid unnecessary detail)
  3. Use sharded documents for large projects

Context limit reached mid-workflow

Section titled “Context limit reached mid-workflow”

Symptom: Workflow stops or loses context partway through.

Solutions:

  1. Save progress frequently (workflows auto-save on Continue)
  2. Break complex sections into multiple sessions
  3. Use step-file architecture (workflows resume from last step)

Common Error Messages

Section titled “Common Error Messages”

”Input file not found”

Section titled “”Input file not found””

Cause: Workflow requires a document that doesn’t exist.

Fix: Complete prerequisite workflow first (e.g., Game Brief before GDD).

”Invalid game type”

Section titled “”Invalid game type””

Cause: Selected game type not in supported list.

Fix: Check game-types.csv for valid type IDs.

”Validation failed”

Section titled “”Validation failed””

Cause: Document doesn’t meet checklist requirements.

Fix: Review the validation output and address flagged items.

Getting Help

Section titled “Getting Help”

Community Support

Section titled “Community Support”

Self-Help

Section titled “Self-Help”
  1. Check workflow-status to understand current state
  2. Review workflow markdown files for expected behavior
  3. Look at completed example documents in the module

Reporting Issues

Section titled “Reporting Issues”

When reporting issues, include:

  1. Which workflow and step
  2. Error message (if any)
  3. Relevant document frontmatter
  4. Steps to reproduce

Next Steps

Section titled “Next Steps”