or run

npx @tessl/cli init
Log in

Version

Tile

Overview

Evals

Files

docs

examples

edge-cases.mdreal-world-scenarios.md

guides

brownfield.mddevelopment-phase.mderror-recovery.mdplanning-phase.mdquick-start.md

reference

agent-teams.mdagents.mdapi-patterns.mdcli.mdconfiguration.mdexpansion-packs.mdprogrammatic-api.mdtasks.mdtemplates.mdworkflows.md
index.md
tile.json

error-recovery.mddocs/guides/

Error Recovery Guide

Common errors, their causes, and step-by-step solutions. Use this guide to quickly resolve issues.

Installation Errors

Error: Node.js version must be >=20.10.0

Cause: Outdated Node.js version

Solution:

# Check current version
node --version

# Upgrade Node.js to v20.10.0 or later
# Visit https://nodejs.org or use nvm:
nvm install 20
nvm use 20

Error: EACCES: permission denied

Cause: Insufficient permissions for installation directory

Solution:

# Option 1: Choose different directory
npx bmad-method install --directory ./my-project

# Option 2: Fix permissions (if appropriate)
chmod u+w /path/to/directory

# Option 3: Use sudo (not recommended)
sudo npx bmad-method install

Error: Installation directory does not exist

Cause: Specified directory doesn't exist

Solution:

# Create directory first
mkdir -p ./my-project
cd ./my-project

# Then install
npx bmad-method install

Configuration Errors

Error: PRD file not found. Expected: docs/prd.md

Cause: PRD hasn't been created yet or wrong path in config

Solution:

# Option 1: Create PRD
*agent pm
*create-prd

# Option 2: Check config
# Edit .bmad-core/core-config.yaml
# Verify prdFile path is correct

Error: Architecture sharded directory not found: docs/architecture

Cause: Architecture not sharded or prdSharded set to true but directory missing

Solution:

# Option 1: Shard architecture
*agent po
*shard-doc

# Option 2: Disable sharding
# Edit .bmad-core/core-config.yaml
architecture:
  architectureSharded: false

Error: Epic file pattern doesn't match: epic1.md

Cause: Epic file naming doesn't match pattern in config

Solution:

# Option 1: Rename files to match pattern
# Pattern: epic-{n}*.md
# Rename: epic1.md → epic-1.md

# Option 2: Update pattern in config
# Edit .bmad-core/core-config.yaml
prd:
  epicFilePattern: epic{n}*.md  # Remove dash

Error: Required file not found: docs/architecture/coding-standards.md

Cause: File listed in devLoadAlwaysFiles doesn't exist

Solution:

# Option 1: Create missing file
# Create docs/architecture/coding-standards.md

# Option 2: Remove from config
# Edit .bmad-core/core-config.yaml
# Remove the file from devLoadAlwaysFiles array

Agent Errors

Error: Agent doesn't recognize commands

Cause: Missing * prefix on commands

Solution:

# Wrong:
help
create-prd

# Correct:
*help
*create-prd

Error: Command not found for agent

Cause: Command doesn't exist for this agent or typo

Solution:

# Check available commands
*help

# Verify agent loaded correctly
# Ensure you've loaded the correct agent file

Error: Agent can't load dependency

Cause: Task, template, or checklist file missing

Solution:

# Check file exists:
ls .bmad-core/tasks/
ls .bmad-core/templates/
ls .bmad-core/checklists/

# Re-install if files missing
npx bmad-method install --force

Planning Phase Errors

Error: PRD creation fails - missing project brief

Cause: PM expects project brief but it doesn't exist

Solution:

# Option 1: Create project brief first
*agent analyst
*create-project-brief

# Option 2: Skip project brief
# Continue without it - PM can work independently

Error: Architecture creation fails - missing PRD

Cause: Architect expects PRD but it doesn't exist

Solution:

# Create PRD first
*agent pm
*create-prd

# Then create architecture
*agent architect
*create-architecture

Error: Sharding fails - document too short

Cause: Document < 100 lines, not worth sharding

Solution:

# Disable sharding for this document
# Edit .bmad-core/core-config.yaml
prd:
  prdSharded: false

Error: Template not found: prd-tmpl.yaml

Cause: Template file missing from installation

Solution:

# Re-install BMad Method
npx bmad-method update --force

# Or check if template exists
ls .bmad-core/templates/prd-tmpl.yaml

Development Phase Errors

Error: Story creation fails - missing epic file

Cause: Epic file doesn't exist or naming doesn't match pattern

Solution:

# Check epic files exist
ls docs/prd/

# Verify naming matches pattern (epic-{n}*.md)
# Ensure PRD is sharded
*agent po
*shard-doc

Error: Story creation fails - missing architecture sections

Cause: Architecture not sharded or required sections missing

Solution:

# Shard architecture
*agent po
*shard-doc

# Verify sections exist
ls docs/architecture/

# Required sections for all stories:
# - tech-stack.md
# - unified-project-structure.md
# - coding-standards.md
# - testing-strategy.md

Error: Dev agent loads PRD directly

Cause: Dev agent not following story-driven pattern

Solution:

# Remind Dev agent:
# "Story contains ALL context. Never load PRD or architecture directly."

# Verify story has complete Dev Notes section
# SM should include all needed context in story

Error: QA gate fails repeatedly

Cause: Quality standards too strict or implementation issues

Solution:

# Option 1: Review and adjust coding standards
# Edit docs/architecture/coding-standards.md

# Option 2: Address QA feedback systematically
*agent dev
*review-qa

# Option 3: Get stakeholder waiver (if appropriate)
*agent qa
*gate  # Select WAIVED with justification

CLI Errors

Error: Update check timed out

Cause: Network issues or npm registry unavailable

Solution:

# Check internet connection
ping npmjs.org

# Try again later
npx bmad-method update-check

# Or skip check and update directly
npx bmad-method update

Error: Flatten command fails - too many files

Cause: Codebase too large (> 100k files)

Solution:

# Flatten specific directory
npx bmad-method flatten -i ./src -o src.xml

# Or exclude directories
# Create/update .gitignore with directories to skip

Error: No IDE selected warning

Cause: User skipped IDE selection during installation

Solution:

# Re-run installer and select IDEs
npx bmad-method install

# During installation, use SPACEBAR to select IDEs

Workflow Errors

Error: Workflow fails - missing prerequisite artifact

Cause: Previous workflow step not completed

Solution:

# Identify missing artifact from error message
# Complete prerequisite step
# Example: Missing prd.md
*agent pm
*create-prd

# Then resume workflow

Error: Agent transformation fails

Cause: Agent file not found or not loaded properly

Solution:

# Verify agent file exists
ls .bmad-core/agents/

# Reload agent
*agent <agent-name>

# If still fails, re-install
npx bmad-method install --force

Error: Conditional step skipped unexpectedly

Cause: Condition evaluated to false

Solution:

# Review workflow conditions
# Example: UX step skipped because no UI needed
# This is expected for backend-only projects

# If unexpected, check workflow definition
cat .bmad-core/workflows/<workflow-name>.yaml

Web Platform Issues

Problem: Web bundle too large

Cause: Team bundle exceeds platform context limit

Solution:

# Option 1: Use smaller team
# team-fullstack → team-no-ui (if no UI needed)

# Option 2: Load individual agents
# Load agents one at a time as needed

# Option 3: Clear context between major phases
# Complete planning → clear context → load dev team

Problem: Agent loses context

Cause: Conversation too long, context window exceeded

Solution:

# Save work to files
*doc-out  # Output document

# Start new conversation
# Load only needed agents for next phase

# Reference saved files as context

Problem: Elicitation overwhelming

Cause: Too many elicitation prompts

Solution:

# Use YOLO mode
*yolo

# Agent will generate without elicitation
# Or answer "1" (Proceed) for each prompt

Brownfield-Specific Errors

Error: Flatten creates huge XML file (> 100MB)

Cause: Very large codebase

Solution:

# Flatten only relevant directories
npx bmad-method flatten -i ./src -o src.xml
npx bmad-method flatten -i ./api -o api.xml

# Provide multiple context files to agents

Error: Integration context unclear

Cause: Existing code patterns not well documented

Solution:

# Use interactive brownfield story creation
*agent pm
*create-brownfield-story

# Answer agent's questions about integration
# Agent will gather context interactively

Error: Breaking existing functionality

Cause: Insufficient safety checks

Solution:

# Add comprehensive tests
# Test existing functionality before and after changes

# Use feature flags
# Implement new code behind flag, enable gradually

# Create rollback plan
# Document in story how to undo changes

Recovery Procedures

Full Reset

If installation is corrupted:

# 1. Backup customizations
cp .bmad-core/core-config.yaml ../core-config-backup.yaml

# 2. Remove BMad
rm -rf .bmad-core

# 3. Re-install
npx bmad-method install

# 4. Restore customizations
cp ../core-config-backup.yaml .bmad-core/core-config.yaml

Partial Recovery

If specific agent broken:

# Re-install specific files
npx bmad-method update --force

# Verify installation
npx bmad-method status

Document Recovery

If documents corrupted:

# Check git history
git log docs/

# Restore from backup
git checkout HEAD~1 docs/prd.md

# Re-generate if needed
*agent pm
*create-prd

Getting Help

Self-Help Resources

  1. Agent Help: *help in any agent for commands
  2. Status Check: npx bmad-method status for installation info
  3. Documentation: Review reference docs for detailed specs
  4. Examples: Check guides for workflow examples

Support Channels

  • GitHub Issues: https://github.com/Agentic-Insights/bmad-method/issues
  • npm Package: https://www.npmjs.com/package/bmad-method
  • Documentation: https://bmad-method.com

Preventive Measures

Avoid Common Errors

  1. Complete each phase: Don't skip planning steps
  2. Verify configuration: Check core-config.yaml settings match your structure
  3. Follow naming conventions: Use patterns specified in config
  4. Test incrementally: Don't wait until end to test
  5. Document as you go: Keep stories and docs updated
  6. Backup regularly: Commit work to git frequently

Related Documentation

  • Quick Start Guide
  • Planning Phase Guide
  • Development Phase Guide
  • Configuration Reference
  • CLI Reference