BMAD-METHOD/docs/how-it-works/troubleshooting.md

BMAD Troubleshooting Guide

This comprehensive guide helps users diagnose and resolve common issues encountered while using the BMAD system.

Quick Diagnostic Checklist

Before diving into specific issues, run through this quick checklist:

• Verify BMAD configuration files are present and valid
• Check network connectivity and API access
• Confirm persona permissions and access rights
• Validate template and checklist file integrity
• Review recent system logs for error messages

Common Issues and Solutions

1. Persona Loading Issues

Symptom: Persona fails to load or respond

Possible Causes:

• Missing or corrupted persona configuration files
• Insufficient permissions
• Network connectivity issues
• Invalid persona syntax

Solutions:

1. Verify Persona Files:

   # Check if persona files exist
   ls -la bmad-agent/personas/
   
   # Validate persona syntax
   bmad validate-persona --persona=po
   

2. Reset Persona Configuration:

   # Backup current config
   cp bmad-config.yml bmad-config.yml.backup
   
   # Reset to default
   bmad reset-config --persona=po
   

3. Check Permissions:

   # Verify file permissions
   chmod 644 bmad-agent/personas/*.md
   

2. Template Generation Failures

Symptom: Templates fail to generate or produce incorrect output

Possible Causes:

• Missing template variables
• Corrupted template files
• Invalid template syntax
• Insufficient data context

Solutions:

1. Validate Template Syntax:

   # Check template validity
   bmad validate-template --template=prd-tmpl.md
   

2. Debug Template Variables:

   # List available variables
   bmad debug-template --template=prd-tmpl.md --show-vars
   

3. Regenerate Template:

   # Force template regeneration
   bmad generate --template=prd-tmpl.md --force
   

3. Checklist Validation Errors

Symptom: Checklists fail validation or show incorrect status

Possible Causes:

• Outdated checklist definitions
• Missing checklist dependencies
• Incorrect task mapping
• Data synchronization issues

Solutions:

1. Update Checklists:

   # Refresh checklist definitions
   bmad update-checklists
   

2. Validate Checklist Mapping:

   # Check task-to-checklist mapping
   bmad validate-mapping --checklist=po-master-checklist.md
   

3. Reset Checklist State:

   # Clear checklist cache
   bmad clear-cache --type=checklists
   

4. Integration Connection Issues

Symptom: External system integrations fail or timeout

Possible Causes:

• Network connectivity problems
• Authentication failures
• API rate limiting
• Service unavailability

Solutions:

1. Test Connectivity:

   # Test API endpoints
   bmad test-connection --service=github
   bmad test-connection --service=jira
   

2. Refresh Authentication:

   # Renew authentication tokens
   bmad auth-refresh --service=github
   

3. Check Rate Limits:

   # Monitor API usage
   bmad status --api-usage
   

5. Performance Issues

Symptom: Slow response times or system lag

Possible Causes:

• Large knowledge base files
• Inefficient queries
• Memory constraints
• Network latency

Solutions:

1. Optimize Knowledge Base:

   # Rebuild search index
   bmad rebuild-index
   
   # Compress knowledge base
   bmad optimize-kb
   

2. Clear System Cache:

   # Clear all caches
   bmad clear-cache --all
   

3. Monitor System Resources:

   # Check system performance
   bmad system-status --detailed
   

Environment-Specific Issues

IDE Environment Issues

VS Code / Cursor Integration

Common Issues:

• Extension not loading
• Configuration not recognized
• Syntax highlighting missing

Solutions:

1. Reinstall BMAD extension
2. Reload VS Code window
3. Check extension compatibility
4. Verify workspace settings

Command Line Issues

Common Issues:

• Command not found
• Permission denied
• Path configuration errors

Solutions:

1. Add BMAD to system PATH
2. Set proper file permissions
3. Verify installation directory
4. Check shell configuration

Web Environment Issues

Browser Compatibility

Common Issues:

• Features not working in specific browsers
• JavaScript errors
• CSS rendering problems

Solutions:

1. Update to supported browser version
2. Clear browser cache and cookies
3. Disable conflicting extensions
4. Check JavaScript console for errors

Authentication Problems

Common Issues:

• Login failures
• Session timeouts
• Permission errors

Solutions:

1. Clear browser storage
2. Verify credentials
3. Check session configuration
4. Review user permissions

Advanced Troubleshooting

Log Analysis

Accessing Logs

# View recent logs
bmad logs --tail=100

# Filter by severity
bmad logs --level=error

# Export logs for analysis
bmad logs --export=bmad-logs.txt

Common Log Patterns

Error Patterns to Look For:

• Authentication failed: Check credentials and permissions
• Template not found: Verify template file paths
• Network timeout: Check connectivity and API status
• Validation failed: Review input data and formats

System Diagnostics

Health Check

# Run comprehensive system check
bmad health-check --comprehensive

# Check specific components
bmad health-check --component=personas
bmad health-check --component=templates
bmad health-check --component=integrations

Performance Profiling

# Profile system performance
bmad profile --duration=60s

# Analyze memory usage
bmad profile --memory

# Check disk usage
bmad profile --disk

Recovery Procedures

Configuration Recovery

# Backup current configuration
bmad backup-config --output=config-backup.tar.gz

# Restore from backup
bmad restore-config --input=config-backup.tar.gz

# Reset to factory defaults
bmad factory-reset --confirm

Data Recovery

# Recover corrupted knowledge base
bmad recover-kb --source=backup

# Rebuild search indices
bmad rebuild-indices --all

# Validate data integrity
bmad validate-data --comprehensive

Getting Help

Self-Service Resources

1. Documentation: Check the comprehensive documentation at /docs/
2. FAQ: Review frequently asked questions
3. Community Forums: Search community discussions
4. Video Tutorials: Watch step-by-step guides

Support Channels

1. GitHub Issues: Report bugs and feature requests
2. Community Discord: Get help from other users
3. Email Support: Contact support team directly
4. Professional Services: Engage for complex implementations

Reporting Issues

When reporting issues, include:

1. System Information:

   bmad system-info --export
   

2. Error Logs:

   bmad logs --level=error --last=24h --export
   

3. Configuration Details:

   bmad config-export --sanitized
   

4. Reproduction Steps:

   • Detailed steps to reproduce the issue
   • Expected vs. actual behavior
   • Screenshots or recordings if applicable

---

Effective troubleshooting ensures smooth BMAD system operation and minimizes downtime.