Troubleshooting Guide

Solutions to common problems with Claude 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:

bash

# 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/yq

Note: There are multiple tools named "yq". Claude Craft requires Mike Farah's version (v4+), not the Python version.

"Permission denied" when running scripts

Problem: Installation scripts are not executable.

Solution:

bash

# 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:

bash

# Create the directory first
mkdir -p ~/my-project

# Then run installation
make install-symfony TARGET=~/my-project

Installation completes but files are missing

Problem: Some files weren't copied during installation.

Diagnosis:

bash

# Check what was installed
ls -la ~/my-project/.claude/

# Count files
find ~/my-project/.claude -name "*.md" | wc -l

Solution:

bash

# Force reinstall
make install-symfony TARGET=~/my-project OPTIONS="--force"

# Or run with verbose output
./Dev/scripts/install-symfony-rules.sh --verbose ~/my-project

NPX cache issues

Problem: NPX uses old cached version of Claude Craft.

Solution:

bash

# Clear NPX cache
npx clear-npx-cache

# Or manually remove
rm -rf ~/.npm/_npx

# Then reinstall
npx @the-bearded-bear/claude-craft install ~/my-project --tech=symfony

Claude Code Issues

Commands not showing up

Problem: Slash commands don't appear in Claude Code.

Diagnosis:

bash

# Verify commands directory exists
ls -la ~/my-project/.claude/commands/

# Check file format
head -20 ~/my-project/.claude/commands/common/pre-commit-check.md

Solutions:

Restart Claude Code session
bash
```
# Exit and restart
exit
claude
```

Check YAML frontmatter is valid

yaml

---
description: Brief description
argument-hint: <arg1> [arg2]
---

Verify file extension is .md

Check Claude Code version

bash

claude --version
# Requires Claude Code 2.1.97+

Agents not responding

Problem: @agent mentions don't trigger the agent behavior.

Diagnosis:

bash

# Check agents directory
ls -la ~/my-project/.claude/agents/

# Verify agent file format
head -20 ~/my-project/.claude/agents/api-designer.md

Solutions:

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:

bash

# Ensure ~/.claude.json has valid structure
# Update Claude Code to v2.1.38+
npm update -g @anthropic-ai/claude-code

Heredoc "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:

bash

# Check skills directory
ls -la ~/my-project/.claude/skills/

# Check context.yaml
cat ~/my-project/.claude/context.yaml

Solutions:

Rescan skills sans redémarrer la session (v2.1.157+)
```
/reload-skills
```
Cette 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

yaml

triggers:
  - pattern: "*.test.ts"
    skills: ["testing"]

Use explicit skill invocation
```
/testing
```
Restart Claude Code if /reload-skills is not available (Requires Claude Code v2.1.157+)
bash
```
exit
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:

bash

# Resume the stalled session
claude --resume <session-id>

# Or use debug mode
/debug

Common 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:

bash

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:

bash

# Add user to docker group
sudo usermod -aG docker $USER

# Log out and back in, or
newgrp docker

# Verify
docker run hello-world

Container not starting

Problem: Docker containers fail to start.

Diagnosis:

bash

# Check container logs
docker compose logs

# Check container status
docker compose ps

# Check for port conflicts
sudo lsof -i :8080

Solutions:

Stop conflicting services

bash

# Kill process using port
sudo kill $(sudo lsof -t -i:8080)

Rebuild containers

bash

docker compose down
docker compose build --no-cache
docker compose up -d

Check Docker resources
bash
```
docker system df
docker system prune -a
```

Volume permission issues

Problem: Files created in Docker have wrong permissions.

Solution:

bash

# 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:

bash

# Initialize workflow (commande correcte — il n'existe pas de /bmad:init)
/workflow:init

# Si les commandes /sprint:* 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: []
EOF

Note : /bmad:init n'est pas une commande valide. Utiliser /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:

/gate:report

Common 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: /sprint:transition fails to update story status.

Solution:

bash

# 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 file

Ralph Wiggum Issues

Infinite loop

Problem: Ralph keeps running without completing.

Solution:

bash

# 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: 3

DoD validators always fail

Problem: Definition of Done validators don't pass.

Diagnosis:

bash

# Check DoD configuration
cat ralph.yml

# Run validators manually
npm test
npm run lint

Common issues:

Command validator fails

yaml

# Verify command works manually
dod:
  - type: command
    command: "npm test"
    expect_exit_code: 0

File 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: /team:sprint --ralph-mode fails immediately.

Diagnosis:

bash

# 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.yaml

Solutions:

Initialize BMAD first (/bmad:init n'existe pas — utiliser /workflow:init)

bash

/workflow:init
# Si la couche project est installée (make install-project TARGET=.) :
/sprint:next-story

Transition stories to ready-for-dev
bash
```
/sprint:transition US-001 ready-for-dev
```

Note: /common:ralph-sprint was removed in v6.0. Use /team:sprint --ralph-mode instead. See Migration Guide.

Configuration Issues

YAML syntax errors

Problem: Configuration files have invalid YAML.

Diagnosis:

bash

# Validate YAML
yq eval '.' claude-projects.yaml

# Or use online validator

Common 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:

bash

# Validate configuration
make config-validate

# Check project name
make config-list

# Install with correct project name
make config-install PROJECT=my-monorepo

Performance 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 -d

Check Claude Code version

bash

claude --version
# Update if needed
npm update -g @anthropic-ai/claude-code

High memory usage

Problem: Claude Code consumes excessive memory.

Solutions:

Flatten large codebases

bash

npx @the-bearded-bear/claude-craft flatten --max-tokens=50000

Use 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:

bash

# Use preserve-config option
make install-symfony TARGET=. OPTIONS="--force --preserve-config"

Recovery:

bash

# 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:

bash

# With scripts
./Dev/scripts/install-symfony-rules.sh --verbose ~/project

# With make
make install-symfony TARGET=~/project OPTIONS="--verbose"

Check Logs

bash

# Claude Code logs
cat ~/.claude/logs/claude-code.log

# Docker logs
docker compose logs -f

Report Issues

If you can't find a solution:

Search existing issues: https://github.com/TheBeardedBearSAS/claude-craft/issues
Create a new issue with:
- Claude Craft version
- OS and version
- Steps to reproduce
- Error messages
- Expected vs actual behavior

Quick Diagnostic Script

Run this to diagnose common issues:

bash

#!/bin/bash
echo "=== Claude 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')"
fi

Save 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 if conditional 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.json naming 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
```
/clear
```
Décomposer les tâches longues avec des sous-agents
```
@tdd-coach Investigate why the test suite is slow
```
Les 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%)
```
/common:setup-rtk
```
Utiliser des modèles allégés pour les sous-agents
bash
```
export CLAUDE_CODE_SUBAGENT_MODEL=sonnet
```
Réduire la charge au démarrage
- Vérifier que .claude/CLAUDE.md est < 200 lignes
- Référencer les fichiers avec @path plutôt que de les copier dans CLAUDE.md

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" malgré une installation valide

Cause 1 : sprint-status.yaml absent

bash

ls .bmad/sprint-status.yaml
# Si absent, initialiser avec :
make install-project TARGET=.
/workflow:init

Cause 2 : format de sprint-status.yaml incorrect

Le Kanban attend un fichier valide avec la structure BMAD v6 :

yaml

version: 2
current_sprint: 1
sprints:
  - number: 1
    goal: "Sprint goal"
    stories:
      - id: "US-001"
        title: "Feature"
        status: "in-progress"
        assigned_to: null   # null autorisé (ne pas mettre "")

Cause 3 : stories créées avec la convention workflow/ (US-*.md)

Depuis v8.11.0, le Kanban ingère .bmad/sprint-status.yaml (convention BMAD v6). Les fichiers workflow/US-*.md (convention /workflow:start) sont une piste séparée. Les deux coexistent — le board n'affiche que les stories de la YAML.

Cause 4 : port déjà utilisé

bash

# Changer le port
npx @the-bearded-bear/claude-craft kanban --port=3142

Troubleshooting Guide ​

Installation Issues ​

"yq: command not found" ​

"Permission denied" when running scripts ​

"Target directory does not exist" ​

Installation completes but files are missing ​

NPX cache issues ​

Claude Code Issues ​

Commands not showing up ​

Agents not responding ​

Plan mode crash (v2.1.38) ​

Heredoc "Bad substitution" errors ​

Tab key queues slash commands instead of autocompleting ​

Skills not loading ​

Stalled Stream Handling (v2.1.105+) ​

WebFetch Token Optimization (v2.1.105+) ​

Docker Issues ​

Docker permission denied ​

Container not starting ​

Volume permission issues ​

BMAD Issues ​

"No sprint-status.yaml found" ​

Quality gate always fails ​

Story transitions not working ​

Ralph Wiggum Issues ​

Infinite loop ​

DoD validators always fail ​

Team Sprint Issues ​

Sprint doesn't start ​

Configuration Issues ​

YAML syntax errors ​

Multi-project config not working ​

Performance Issues ​

Slow command execution ​

High memory usage ​

Files overwritten after update ​

Getting More Help ​

Debug Mode ​

Check Logs ​

Report Issues ​

Quick Diagnostic Script ​

Hook Event Issues (v8.x) ​

Hook not triggering ​

PreCompact hook not blocking ​

Subprocess Sandboxing Issues ​

"PID namespace not available" ​

"Permission denied" in sandboxed subprocess ​

MCP Tool Search Issues ​

Tools not lazy-loading ​

Managed Settings Issues ​

Settings not merging ​

Context Window Issues ​

Symptoms ​

Recovery Steps ​

Kanban Board Empty ​

"Board is empty" malgré une installation valide ​

Troubleshooting Guide

Installation Issues

"yq: command not found"

"Permission denied" when running scripts

"Target directory does not exist"

Installation completes but files are missing

NPX cache issues

Claude Code Issues

Commands not showing up

Agents not responding

Plan mode crash (v2.1.38)

Heredoc "Bad substitution" errors

Tab key queues slash commands instead of autocompleting

Skills not loading

Stalled Stream Handling (v2.1.105+)

WebFetch Token Optimization (v2.1.105+)

Docker Issues

Docker permission denied

Container not starting

Volume permission issues

BMAD Issues

"No sprint-status.yaml found"

Quality gate always fails

Story transitions not working

Ralph Wiggum Issues

Infinite loop

DoD validators always fail

Team Sprint Issues

Sprint doesn't start

Configuration Issues

YAML syntax errors

Multi-project config not working

Performance Issues

Slow command execution

High memory usage

Files overwritten after update

Getting More Help

Debug Mode

Check Logs

Report Issues

Quick Diagnostic Script

Hook Event Issues (v8.x)

Hook not triggering

PreCompact hook not blocking

Subprocess Sandboxing Issues

"PID namespace not available"

"Permission denied" in sandboxed subprocess

MCP Tool Search Issues

Tools not lazy-loading

Managed Settings Issues

Settings not merging

Context Window Issues

Symptoms

Recovery Steps

Kanban Board Empty

"Board is empty" malgré une installation valide