Troubleshooting Guide
Solutions to common problems with Bear Craft.
Installation Issues
"yq: command not found"
Problem: The installation scripts require yq but it's not installed or the wrong version is installed.
Solution:
# Check current version (if any)
which yq
yq --version
# Install correct version (Mike Farah's yq v4)
# macOS
brew install yq
# Ubuntu/Debian
sudo apt install yq
# Or download binary directly
sudo wget https://github.com/mikefarah/yq/releases/latest/download/yq_linux_amd64 -O /usr/local/bin/yq
sudo chmod +x /usr/local/bin/yqNote: There are multiple tools named "yq". Bear Craft requires Mike Farah's version (v4+), not the Python version.
"Permission denied" when running scripts
Problem: Installation scripts are not executable.
Solution:
# Make all scripts executable
chmod +x Dev/scripts/*.sh
# Or use make
make fix-permissions
# Or run with bash directly
bash Dev/scripts/install-symfony-rules.sh --lang=en ~/my-project"Target directory does not exist"
Problem: The target project directory doesn't exist.
Solution:
# Create the directory first
mkdir -p ~/my-project
# Then run installation
make install-symfony TARGET=~/my-projectInstallation completes but files are missing
Problem: Some files weren't copied during installation.
Diagnosis:
# Check what was installed
ls -la ~/my-project/.claude/
# Count files
find ~/my-project/.claude -name "*.md" | wc -lSolution:
# Force reinstall
make install-symfony TARGET=~/my-project OPTIONS="--force"
# Or run with verbose output
./Dev/scripts/install-symfony-rules.sh --verbose ~/my-projectNPX cache issues
Problem: NPX uses old cached version of Bear Craft.
Solution:
# Clear NPX cache
npx clear-npx-cache
# Or manually remove
rm -rf ~/.npm/_npx
# Then reinstall
npx @the-bearded-bear/bear-craft install ~/my-project --tech=symfonyClaude Code Issues
Commands not showing up
Problem: Slash commands don't appear in Claude Code.
Diagnosis:
# Verify commands directory exists
ls -la ~/my-project/.claude/commands/
# Check file format
head -20 ~/my-project/.claude/commands/bear-common/pre-commit-check.mdSolutions:
Restart Claude Code session
bash# Exit and restart exit claudeCheck YAML frontmatter is valid
yaml--- description: Brief description argument-hint: <arg1> [arg2] ---Verify file extension is
.mdCheck Claude Code version
bashclaude --version # Requires Claude Code 2.1.325+
Agents not responding
Problem: @agent mentions don't trigger the agent behavior.
Diagnosis:
# Check agents directory
ls -la ~/my-project/.claude/agents/
# Verify agent file format
head -20 ~/my-project/.claude/agents/api-designer.mdSolutions:
Use exact agent name
# Correct @api-designer Help me design... # Incorrect @API-Designer Help me design... @apidesigner Help me design...Check frontmatter format
yaml--- name: api-designer description: Expert in REST/GraphQL API design ---
Plan mode crash (v2.1.38)
Problem: Claude Code crashes when entering plan mode.
Cause: Project config in ~/.claude.json is missing default fields.
Solution:
# Ensure ~/.claude.json has valid structure
# Update Claude Code to v2.1.38+
npm update -g @anthropic-ai/claude-codeHeredoc "Bad substitution" errors
Problem: Bash tool produces "Bad substitution" errors with JavaScript template literals like ${index + 1} in heredocs.
Solution: Update Claude Code to v2.1.38+ which fixes heredoc parsing for JS template literals.
Tab key queues slash commands instead of autocompleting
Problem: Pressing Tab queues slash commands instead of triggering autocomplete.
Solution: Update Claude Code to v2.1.38+ which fixes Tab key behavior.
Skills not loading
Problem: Skills don't activate when triggered.
Diagnosis:
# Check skills directory
ls -la ~/my-project/.claude/skills/
# Check context.yaml
cat ~/my-project/.claude/context.yamlSolutions:
Rescan skills sans redémarrer la session (v2.1.157+)
/reload-skillsCette commande est distincte de
/reload-plugins(qui recharge les MCP). À utiliser après tout ajout ou modification d'un fichier skill.Verify context.yaml format
yamltriggers: - pattern: "*.test.ts" skills: ["testing"]Use explicit skill invocation
/testingRestart Claude Code if /reload-skills is not available (Requires Claude Code v2.1.157+)
bashexit claude
Stalled Stream Handling (v2.1.105+)
Problem: Claude Code appears frozen with no response for 5+ minutes.
Solution: Claude Code v2.1.105+ automatically detects stalled streams with a 5-minute timeout and automatic retry mechanism.
Manual recovery:
# Resume the stalled session
claude --resume <session-id>
# Or use debug mode
/debugCommon causes:
- Network interruptions or unstable connections
- API rate limiting
- Large file operations (reading/writing very large files)
- MCP server hangs or unresponsive external tools
Prevention:
- Keep Claude Code updated to v2.1.105+
- Monitor network stability during long operations
- Break down large file operations into smaller chunks
- Review MCP server logs if using external tools
WebFetch Token Optimization (v2.1.105+)
Problem: WebFetch consuming excessive tokens when fetching web pages.
Solution: Claude Code v2.1.105+ automatically strips <style> and <script> tag contents, reducing token consumption by 50-80%.
Features:
- Automatic optimization (no configuration needed)
- Preserves semantic HTML structure
- Removes inline CSS and JavaScript
- Keeps essential page content
Note: This optimization is automatic in v2.1.105+. If you're experiencing high token usage from web fetches, update Claude Code:
npm update -g @anthropic-ai/claude-code
claude --version # Verify v2.1.105+Docker Issues
Docker permission denied
Problem: Can't run Docker commands without sudo.
Solution:
# Add user to docker group
sudo usermod -aG docker $USER
# Log out and back in, or
newgrp docker
# Verify
docker run hello-worldContainer not starting
Problem: Docker containers fail to start.
Diagnosis:
# Check container logs
docker compose logs
# Check container status
docker compose ps
# Check for port conflicts
sudo lsof -i :8080Solutions:
Stop conflicting services
bash# Kill process using port sudo kill $(sudo lsof -t -i:8080)Rebuild containers
bashdocker compose down docker compose build --no-cache docker compose up -dCheck Docker resources
bashdocker system df docker system prune -a
Volume permission issues
Problem: Files created in Docker have wrong permissions.
Solution:
# Fix ownership
sudo chown -R $(id -u):$(id -g) ./
# Or use user in docker-compose.yml
services:
app:
user: "${UID}:${GID}"BMAD Issues
"No sprint-status.yaml found"
Problem: BMAD commands fail because sprint-status.yaml doesn't exist.
Solution:
# Initialize workflow (commande correcte — il n'existe pas de /bmad:init)
/bear-workflow:init
# Si les commandes /bear-gate:* et /bear-project:* sont absentes, installer la couche Project d'abord :
make install-project TARGET=.
# Ou créer le fichier manuellement
mkdir -p .bmad
cat > .bmad/sprint-status.yaml << 'EOF'
version: 2
current_sprint: 1
sprints:
- number: 1
goal: "Initial sprint"
stories: []
EOFNote :
/bmad:initn'est pas une commande valide. Utiliser/bear-workflow:init(installé par défaut) pour initialiser le workflow BMAD.
Quality gate always fails
Problem: Quality gates fail even when criteria seem met.
Diagnosis:
/bear-gate:check allCommon causes:
Missing required fields
- PRD must have: problem, users, goals, metrics, scope
- Story must have: AC, estimate, tasks
Format issues
- YAML syntax errors in story files
- Missing frontmatter
Threshold not met
- PRD Gate: ≥80%
- Tech Spec Gate: ≥90%
- Story DoD: 100%
Story transitions not working
Problem: /bear-project:backlog move story fails to update story status.
Solution:
# Check current status
cat .bmad/backlog/US-001.md
# Valid transitions:
# backlog → ready-for-dev
# ready-for-dev → in-progress
# in-progress → review
# review → done
# any → blocked
# Manual fix if needed
# Edit the frontmatter in the story fileRalph Wiggum Issues
Infinite loop
Problem: Ralph keeps running without completing.
Solution:
# Ralph has built-in circuit breaker
# Default: 10 iterations max
# Check ralph.yml for limits
cat ralph.yml
# Adjust limits
max_iterations: 5
circuit_breaker:
enabled: true
threshold: 3DoD validators always fail
Problem: Definition of Done validators don't pass.
Diagnosis:
# Check DoD configuration
cat ralph.yml
# Run validators manually
npm test
npm run lintCommon issues:
Command validator fails
yaml# Verify command works manually dod: - type: command command: "npm test" expect_exit_code: 0File changed validator fails
yaml# Check file paths are correct dod: - type: file_changed path: "src/feature/*.ts"
Team Sprint Issues
Sprint doesn't start
Problem: /bear-team:delivery --phase=implementation --engine=teams --ralph-mode fails immediately.
Diagnosis:
# Check BMAD is initialized
ls .bmad/sprint-status.yaml
# Check for ready stories
yq '.stories | to_entries[] | select(.value.status == "ready-for-dev")' .bmad/sprint-status.yamlSolutions:
Initialize BMAD first (
/bmad:initn'existe pas — utiliser/bear-workflow:init)bash/bear-workflow:init # Si la couche project est installée (make install-project TARGET=.) : /bear-project:backlog next storyTransition stories to ready-for-dev
bash/bear-project:backlog move story US-001 ready-for-dev
Note:
/bear-common:ralph-sprintwas removed in v6.0. Use/bear-team:delivery --phase=implementation --engine=teams --ralph-modeinstead. See Migration Guide.
Configuration Issues
YAML syntax errors
Problem: Configuration files have invalid YAML.
Diagnosis:
# Validate YAML
yq eval '.' claude-projects.yaml
# Or use online validatorCommon issues:
Indentation errors
yaml# Wrong projects: - name: "test" modules: - path: "src" # Correct projects: - name: "test" modules: - path: "src"Unquoted special characters
yaml# Wrong description: This is a test: value # Correct description: "This is a test: value"
Multi-project config not working
Problem: make config-install fails for monorepo setup.
Solution:
# Validate configuration
make config-validate
# Check project name
make config-list
# Install with correct project name
make config-install PROJECT=my-monorepoPerformance Issues
Slow command execution
Problem: Commands take too long to complete.
Solutions:
Reduce context size
- Use TCL structure (default in v4)
- Reference only needed files with
@
Optimize Docker
bash# Use build cache docker compose build # Don't rebuild every time docker compose up -dCheck Claude Code version
bashclaude --version # Update if needed npm update -g @anthropic-ai/claude-code
High memory usage
Problem: Claude Code consumes excessive memory.
Solutions:
Flatten large codebases
bashnpx @the-bearded-bear/bear-craft flatten --max-tokens=50000Use document sharding
- Automatic when max-tokens is set
Exclude large files
bash# Add to .gitignore or .claudeignore *.log node_modules/ vendor/
Files overwritten after update
Problem: Custom configurations lost after reinstall.
Prevention:
# Use preserve-config option
make install-symfony TARGET=. OPTIONS="--force --preserve-config"Recovery:
# If you had backups
ls .claude.backup/
# Restore specific files
cp .claude.backup/rules/00-project-context.md .claude/rules/Getting More Help
Debug Mode
Enable verbose output:
# With scripts
./Dev/scripts/install-symfony-rules.sh --verbose ~/project
# With make
make install-symfony TARGET=~/project OPTIONS="--verbose"Check Logs
# Claude Code logs
cat ~/.claude/logs/claude-code.log
# Docker logs
docker compose logs -fReport Issues
If you can't find a solution:
- Search existing issues: https://github.com/TheBeardedBearSAS/bear-craft/issues
- Create a new issue with:
- Bear Craft version
- OS and version
- Steps to reproduce
- Error messages
- Expected vs actual behavior
Quick Diagnostic Script
Run this to diagnose common issues:
#!/bin/bash
echo "=== Bear Craft Diagnostics ==="
echo -e "\n--- System Info ---"
echo "OS: $(uname -a)"
echo "Shell: $SHELL"
echo -e "\n--- Dependencies ---"
for cmd in node npm yq jq git docker make; do
if command -v $cmd &> /dev/null; then
echo "[OK] $cmd: $($cmd --version 2>&1 | head -n1)"
else
echo "[MISSING] $cmd"
fi
done
echo -e "\n--- Claude Code ---"
if command -v claude &> /dev/null; then
echo "[OK] Claude Code: $(claude --version 2>&1 | head -n1)"
else
echo "[MISSING] Claude Code CLI"
fi
echo -e "\n--- Project Structure ---"
if [ -d ".claude" ]; then
echo "Commands: $(find .claude/commands -name '*.md' 2>/dev/null | wc -l)"
echo "Agents: $(find .claude/agents -name '*.md' 2>/dev/null | wc -l)"
echo "References: $(find .claude/references -name '*.md' 2>/dev/null | wc -l)"
else
echo "[MISSING] .claude directory"
fi
echo -e "\n--- Docker ---"
if command -v docker &> /dev/null; then
echo "Docker running: $(docker info 2>&1 | grep -q 'Server Version' && echo 'Yes' || echo 'No')"
fiSave as diagnose.sh and run with bash diagnose.sh.
Hook Event Issues (v8.x)
Hook not triggering
Problem: PreToolUse, PostToolUse, or new hook events don't execute.
Solutions:
- Verify hook JSON syntax:
jq empty .claude/settings.json - Check Claude Code version: v2.1.76+ required for most new hooks
- Verify matcher is correct (
auto,compact,explicit,always) - Check
ifconditional field syntax (v2.1.85+)
PreCompact hook not blocking
Problem: PreCompact hook with exit code 2 doesn't block compaction.
Solution: Requires Claude Code v2.1.105+. Check version with claude --version.
Subprocess Sandboxing Issues
"PID namespace not available"
Problem: Linux system doesn't support PID namespaces.
Solution: Set CLAUDE_CODE_SUBPROCESS_ENV_SCRUB=1 for standard isolation without PID namespaces.
"Permission denied" in sandboxed subprocess
Problem: Subprocess lacks required permissions.
Solution: Check sandbox.failIfUnavailable in settings. Set to false for graceful degradation.
MCP Tool Search Issues
Tools not lazy-loading
Problem: MCP tools load eagerly instead of via Tool Search.
Solution: Update Claude Code to v2.1.80+ which includes Tool Search. Check with claude --version.
Managed Settings Issues
Settings not merging
Problem: Files in managed-settings.d/ aren't being applied.
Solutions:
- Verify files use
NN-name.jsonnaming pattern - Check JSON syntax:
for f in .claude/managed-settings.d/*.json; do jq empty "$f"; done - Files merge alphabetically — later files override earlier ones
- Requires Claude Code v2.1.83+
Context Window Issues
Symptoms
- Claude répète des informations déjà fournies
- Les réponses deviennent moins précises ou confondent des tâches différentes
- Erreurs malgré des instructions claires
- "Context window exceeded" ou compaction automatique déclenchée en pleine tâche
Recovery Steps
Nettoyer le contexte entre tâches non liées
/clearDécomposer les tâches longues avec des sous-agents
@tdd-coach Investigate why the test suite is slowLes sous-agents ont leur propre fenêtre de contexte et n'affectent pas le contexte principal.
Installer RTK pour réduire la consommation de tokens (60-90%)
/bear-common:setup-rtkUtiliser des modèles allégés pour les sous-agents
bashexport CLAUDE_CODE_SUBAGENT_MODEL=sonnetRéduire la charge au démarrage
- Vérifier que
.claude/CLAUDE.mdest < 200 lignes - Référencer les fichiers avec
@pathplutôt que de les copier dans CLAUDE.md
- Vérifier que
Tableau de bord : Surveiller le % de contexte dans la status line de Claude Code.
| Contexte utilisé | Action recommandée |
|---|---|
| < 30% | Normal |
| 30-60% | Surveiller, éviter les lectures inutiles |
| 60-80% | Déléguer aux sous-agents, envisager /clear |
| > 80% | Compaction imminente — lancer /compact proactivement |
Voir .claude/rules/12-context-management.md pour le guide complet.
Kanban Board Empty
"Board is empty" ou story absente malgré une installation valide
D'abord : le bandeau de diagnostics. Quand un fichier du projet ne peut pas être lu (frontmatter malformé, YAML invalide, fichier refusé par le schéma), le Kanban l'écarte et affiche un bandeau « Some project files could not be read » avec le fichier et la cause. La même liste est renvoyée par :
curl -s http://127.0.0.1:3737/api/diagnosticsCause 1 : sprint-status.yaml absent
ls .bmad/sprint-status.yaml
# Si absent, initialiser avec :
make install-project TARGET=.
/bear-workflow:initCause 2 : format de sprint-status.yaml incorrect
Le Kanban attend la structure du template (Project/templates/sprint-status.yaml.template) : metadata (avec sprint_id, name, start_date, end_date) et stories indexé par identifiant. Les dates sont entre guillemets ; assigned_to: null est autorisé (ne pas mettre "") :
version: "1.0"
metadata:
sprint_id: "sprint-1"
name: "Sprint 1"
start_date: "2026-11-02"
end_date: "2026-11-13"
goal: "Sprint goal"
stories:
US-001:
title: "Feature"
status: "in-progress"
previous_status: "ready-for-dev"
assigned_to: null
story_points: 3
epic_id: "EPIC-001"Les identifiants de la forme US-E4-02 sont acceptés. Une liste sprints: avec number et stories: en tableau (ancien exemple de ce guide) est refusée.
Cause 3 : fichiers US-*.md et YAML
Les fichiers project-management/backlog/user-stories/US-*.md portent le contenu des stories ; .bmad/sprint-status.yaml porte leur statut. Le Kanban lit les deux et les fusionne : une story qui n'existe que dans l'un des deux apparaît quand même. Un US-*.md dont le frontmatter est malformé est signalé par le bandeau de diagnostics au lieu de vider le tableau.
Cause 4 : port déjà utilisé
# Changer le port (forme avec « = » obligatoire)
npx @the-bearded-bear/bear-craft kanban --port=3142--port 4000 (avec une espace) est refusé avec un message d'usage : écrire --port=4000.
Erreurs lors d'une modification depuis le tableau
| Réponse | Signification | Que faire |
|---|---|---|
423 locked | Un script (.bmad/lib/) ou une autre session tient le verrou de .bmad/sprint-status.yaml | Réessayer. Un verrou laissé par un processus interrompu est repris au bout de 10 secondes |
409 conflict | La story a été modifiée ailleurs depuis son chargement | Recharger la story (l'interface le propose), puis refaire la modification |
409 sprint_status_invalid | .bmad/sprint-status.yaml ne passe pas la validation ; rien n'a été écrit | Corriger le fichier (voir la cause 2 et le bandeau de diagnostics) |
409 sprint_status_missing | Création d'une story sans .bmad/sprint-status.yaml | Créer le fichier (cause 1) |
409 invalid_transition | Transition ou gate refusé | Choisir une colonne proposée par le menu « Déplacer » ; voir la machine d'états |
403 readonly | Le serveur tourne avec --readonly | Relancer sans --readonly |
Un onglet du tableau ne se charge pas
Un navigateur n'ouvre que six connexions simultanées vers un même serveur, et chaque tableau visible en garde une pour le temps réel. Un tableau en arrière-plan rend la sienne et la reprend quand on y revient. Avec plus de six tableaux visibles en même temps dans le même navigateur (fenêtres côte à côte), le suivant attend : fermer une fenêtre ou la passer en arrière-plan.