358 lines
7.2 KiB
Markdown
358 lines
7.2 KiB
Markdown
# 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:**
|
|
```bash
|
|
# Check if persona files exist
|
|
ls -la bmad-agent/personas/
|
|
|
|
# Validate persona syntax
|
|
bmad validate-persona --persona=po
|
|
```
|
|
|
|
2. **Reset Persona Configuration:**
|
|
```bash
|
|
# Backup current config
|
|
cp bmad-config.yml bmad-config.yml.backup
|
|
|
|
# Reset to default
|
|
bmad reset-config --persona=po
|
|
```
|
|
|
|
3. **Check Permissions:**
|
|
```bash
|
|
# 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:**
|
|
```bash
|
|
# Check template validity
|
|
bmad validate-template --template=prd-tmpl.md
|
|
```
|
|
|
|
2. **Debug Template Variables:**
|
|
```bash
|
|
# List available variables
|
|
bmad debug-template --template=prd-tmpl.md --show-vars
|
|
```
|
|
|
|
3. **Regenerate Template:**
|
|
```bash
|
|
# 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:**
|
|
```bash
|
|
# Refresh checklist definitions
|
|
bmad update-checklists
|
|
```
|
|
|
|
2. **Validate Checklist Mapping:**
|
|
```bash
|
|
# Check task-to-checklist mapping
|
|
bmad validate-mapping --checklist=po-master-checklist.md
|
|
```
|
|
|
|
3. **Reset Checklist State:**
|
|
```bash
|
|
# 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:**
|
|
```bash
|
|
# Test API endpoints
|
|
bmad test-connection --service=github
|
|
bmad test-connection --service=jira
|
|
```
|
|
|
|
2. **Refresh Authentication:**
|
|
```bash
|
|
# Renew authentication tokens
|
|
bmad auth-refresh --service=github
|
|
```
|
|
|
|
3. **Check Rate Limits:**
|
|
```bash
|
|
# 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:**
|
|
```bash
|
|
# Rebuild search index
|
|
bmad rebuild-index
|
|
|
|
# Compress knowledge base
|
|
bmad optimize-kb
|
|
```
|
|
|
|
2. **Clear System Cache:**
|
|
```bash
|
|
# Clear all caches
|
|
bmad clear-cache --all
|
|
```
|
|
|
|
3. **Monitor System Resources:**
|
|
```bash
|
|
# 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
|
|
|
|
```bash
|
|
# 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
|
|
|
|
```bash
|
|
# 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
|
|
|
|
```bash
|
|
# Profile system performance
|
|
bmad profile --duration=60s
|
|
|
|
# Analyze memory usage
|
|
bmad profile --memory
|
|
|
|
# Check disk usage
|
|
bmad profile --disk
|
|
```
|
|
|
|
### Recovery Procedures
|
|
|
|
#### Configuration Recovery
|
|
|
|
```bash
|
|
# 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
|
|
|
|
```bash
|
|
# 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:**
|
|
```bash
|
|
bmad system-info --export
|
|
```
|
|
|
|
2. **Error Logs:**
|
|
```bash
|
|
bmad logs --level=error --last=24h --export
|
|
```
|
|
|
|
3. **Configuration Details:**
|
|
```bash
|
|
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.*
|