Troubleshooting Guide

This guide covers common issues and their solutions when using Claude-Craft.

Installation Issues
Agent Issues
Command Issues
Configuration Issues
Tool Issues
Performance Issues
Getting Help

Installation Issues

Commands Not Recognized After Installation

Symptoms:

Slash commands like /symfony:check-compliance don't work
Claude doesn't recognize installed commands

Solutions:

Restart Claude Code

bash

# Exit Claude Code completely
exit

# Start fresh
claude

Verify installation

bash

ls -la .claude/commands/
# Should show command directories

Check command file format

bash

head -5 .claude/commands/symfony/check-compliance.md
# Should start with proper markdown header

Files Not Found During Installation

Symptoms:

"Source file not found" errors
Missing rules or templates

Solutions:

Verify Claude-Craft path

bash

# Check you're running from claude-craft directory
pwd
ls -la Dev/scripts/

Check language files exist
bash
```
ls -la Dev/i18n/en/Symfony/rules/
```

Use absolute TARGET path

bash

# Instead of
make install-symfony TARGET=./backend

# Use
make install-symfony TARGET=/full/path/to/backend

Permission Denied Errors

Symptoms:

Can't execute installation scripts
Can't write to target directory

Solutions:

Make scripts executable

bash

chmod +x Dev/scripts/*.sh
chmod +x Project/*.sh
chmod +x Infra/*.sh
chmod +x Tools/*/*.sh

Check target directory permissions

bash

ls -la ~/my-project/
# Ensure you have write permissions

Run with appropriate user

bash

# Don't use sudo unless necessary
# Check directory ownership
ls -la ~/my-project

Installation Creates Empty Directory

Symptoms:

.claude/ directory created but empty or missing files

Solutions:

Check for errors in output

bash

# Run with verbose output
make install-symfony TARGET=./backend 2>&1 | tee install.log

Verify source exists
bash
```
ls -la Dev/i18n/en/Symfony/
```

Try direct script execution

bash

./Dev/scripts/install-symfony-rules.sh --lang=en ./backend

Agent Issues

Agent Not Available

Symptoms:

@api-designer or other agents don't respond
"Unknown agent" type errors

Solutions:

Verify agent files exist

bash

ls -la .claude/agents/
# Should list agent .md files

Check agent file format

bash

head -20 .claude/agents/api-designer.md
# Should have proper frontmatter with name and description

Reinstall agents

bash

make install-common TARGET=. OPTIONS="--force"

Agent Gives Irrelevant Responses

Symptoms:

Agent doesn't follow its specialized instructions
Generic responses instead of expert advice

Solutions:

Provide more context

markdown

@symfony-reviewer Review my UserService implementation

Context:
- Symfony 7 with API Platform
- Clean Architecture
- DDD approach

Code to review:
[paste code here]

Be specific in your request

markdown

# Instead of
@database-architect Help with my database

# Use
@database-architect Design the schema for User aggregate with:
- User entity (id, email, password_hash)
- Role entity (many-to-many with User)
- Permission entity (many-to-many with Role)
- Audit trail for user changes

Check project context file

bash

cat .claude/references/<your-tech>/project-context.md
# Ensure it describes your project accurately

Agent Conflicts with Project Rules

Symptoms:

Agent suggestions contradict project conventions
Inconsistent advice

Solutions:

Update project context
- Add specific conventions to 00-project-context.md
- Include team preferences and constraints

Be explicit in requests

markdown

@api-designer Design endpoint following our RESTful conventions
(see 00-project-context.md for our API standards)

Command Issues

Command Not Found

Symptoms:

/symfony:generate-crud returns "unknown command"
Command suggestions don't appear

Solutions:

Check command directory

bash

ls .claude/commands/symfony/
# Should include generate-crud.md

Verify namespace

bash

# Commands are in format: /{namespace}:{command}
# Available namespaces:
ls .claude/commands/
# common/, symfony/, flutter/, python/, react/, reactnative/, docker/

List available commands
bash
```
# In Claude Code, type:
/help
```

Command Execution Errors

Symptoms:

Command starts but fails
Unexpected output or errors

Solutions:

Check prerequisites
- Some commands require specific tools
- Verify required dependencies installed

Review command file

bash

cat .claude/commands/symfony/generate-crud.md
# Understand what the command expects

Provide required parameters

bash

# Instead of
/symfony:generate-crud

# Use
/symfony:generate-crud User --with-api --with-tests

Command Output Incorrect

Symptoms:

Generated code doesn't match project style
Wrong technology patterns used

Solutions:

Update project context

bash

# Edit .claude/references/<your-tech>/project-context.md
# Add specific patterns and conventions

Customize templates

bash

# Edit templates in .claude/templates/
# Adjust to match your project style

Configuration Issues

YAML Configuration Invalid

Symptoms:

make config-validate fails
Syntax errors in configuration

Solutions:

Check YAML syntax

bash

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

Common YAML errors:

yaml

# Wrong: inconsistent indentation
projects:
  - name: "project"
    path: "/path"  # 2 spaces
     technologies: ["symfony"]  # 3 spaces - ERROR!

# Correct: consistent indentation
projects:
  - name: "project"
    path: "/path"
    technologies: ["symfony"]

Validate with tool

bash

make config-validate CONFIG=claude-projects.yaml

Project Not Found in Configuration

Symptoms:

"Project not found" when installing
Project not listed

Solutions:

Check project name spelling

bash

# List projects
make config-list CONFIG=claude-projects.yaml

# Names are case-sensitive

Verify configuration file path

bash

# Default looks for claude-projects.yaml in current directory
# Specify explicitly:
make config-install CONFIG=/path/to/config.yaml PROJECT=myproject

Configuration Not Applied

Symptoms:

Changes to config don't take effect
Old settings persist

Solutions:

Reinstall with force

bash

make config-install CONFIG=claude-projects.yaml PROJECT=myproject OPTIONS="--force"

Check for conflicts

bash

# Remove existing installation
rm -rf /path/to/project/.claude

# Reinstall
make config-install CONFIG=claude-projects.yaml PROJECT=myproject

Tool Issues

StatusLine Not Displaying

Symptoms:

Status bar empty or default
Custom status line not showing

Solutions:

Verify script installed

bash

ls -la ~/.claude/statusline.sh
# Should exist and be executable

Check settings.json

bash

cat ~/.claude/settings.json | jq '.statusLine'
# Should show:
# {
#   "type": "command",
#   "command": "~/.claude/statusline.sh"
# }

Test script manually

bash

echo '{"model":{"display_name":"Test","id":"claude-opus"}}' | ~/.claude/statusline.sh
# Should output formatted status line

Check for jq

bash

which jq
# Install if missing: brew install jq / apt install jq

MultiAccount Profile Issues

Symptoms:

Can't switch profiles
Profile not recognized

Solutions:

List profiles
bash
```
./claude-accounts.sh list
```

Check profile directory

bash

ls -la ~/.claude-profiles/
# Should contain profile directories

Verify profile mode file

bash

cat ~/.claude-profiles/myprofile/.mode
# Should contain "shared" or "isolated"

Recreate problematic profile

bash

./claude-accounts.sh remove myprofile
./claude-accounts.sh add myprofile --mode=shared

ProjectConfig yq Errors

Symptoms:

"yq: command not found"
YAML parsing errors

Solutions:

Install yq

bash

# macOS
brew install yq

# Linux
sudo snap install yq
# or
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

Verify yq version

bash

yq --version
# Should be v4.x (mikefarah/yq, not kislyuk/yq)

Hook Issues

Hook Not Firing

Symptoms:

PreToolUse/PostToolUse hooks don't execute
No output from hook commands

Solutions:

Verify hook configuration in settings.json
bash
```
cat .claude/settings.json | jq '.hooks'
```

Check matcher syntax

json

{
  "hooks": {
    "PreToolUse": [{
      "matcher": "Bash",
      "hooks": [{"type": "command", "command": "echo test"}]
    }]
  }
}

The matcher must match the tool name exactly (e.g., Bash, Edit, Write).

Test hook command independently

bash

# Run the hook command manually to verify it works
bash -c 'echo test'

PreCompact Hook Blocking

Symptoms:

Context compaction not happening when expected
Compaction seems stuck

Solution: PreCompact hooks (v2.1.105+) can block compaction with exit code 2. Check your hooks:

bash

cat .claude/settings.json | jq '.hooks.PreCompact'
# Ensure hook scripts don't accidentally return exit code 2

Sandbox Errors

Symptoms:

"Sandbox unavailable" errors
Subprocess permission issues

Solutions:

Check Claude Code version (sandboxing requires v2.1.98+)
bash
```
claude --version
```

On Linux, verify PID namespace support

bash

# Check if unshare is available
which unshare

Disable strict sandbox if needed (not recommended for security)
- Remove sandbox.failIfUnavailable from settings if it was added

If using MCP servers with hooks, ensure Claude Code v2.1.97+ to avoid known CVEs:

CVE-2025-59536: Command injection via MCP inputs in hook pipeline
CVE-2026-35020: Compound command bypass
CVE-2026-35022: Env-var prefix injection

Performance Issues

Slow Command Execution

Symptoms:

Commands take long to respond
StatusLine updates slowly

Solutions:

Check cache settings

bash

# In ~/.claude/statusline.conf
SESSION_CACHE_TTL=60   # Reduce if too slow
WEEKLY_CACHE_TTL=300   # Reduce if too slow

Clear caches
bash
```
rm /tmp/.ccusage_*
```
Check network
- Some features require network (ccusage)
- Slow network = slow updates

Large Context Window Usage

Symptoms:

Context indicator shows high percentage quickly
"Context limit" warnings

Solutions:

Use /context for optimization suggestions (v2.1.74+)
bash
```
/context
```

Adjust effort level for simple tasks (v2.1.72+)

bash

/effort low    # Simple lookups
/effort medium # Standard work

Proactively compact at ~70% usage
bash
```
/compact
```
Use /clear between unrelated tasks

Save key learnings before compaction

bash

/memory "Important: auth uses JWT RS256 with 15min expiry"

Set up RTK for 55-65% token savings
bash
```
/common:setup-rtk
```

Use agents for complex tasks

markdown

# Instead of pasting entire codebase
@research-assistant Find all authentication-related files in src/

Getting Help

Check Documentation

Main docs: docs/ directory
Agent reference: docs/AGENTS.md
Commands reference: docs/COMMANDS.md
Technologies guide: docs/TECHNOLOGIES.md

Get Version Info

bash

# Installation scripts
./Dev/scripts/install-symfony-rules.sh --version

# Tools
./Tools/MultiAccount/claude-accounts.sh --version
./Tools/ProjectConfig/claude-projects.sh --version

Report Issues

If you encounter bugs:

Gather information:
- Claude-Craft version
- Operating system
- Steps to reproduce
- Error messages
Check existing issues on GitHub
Create new issue with details

Ask for Help

markdown

@research-assistant I'm having trouble with [describe issue]

Environment:
- OS: [your OS]
- Claude-Craft version: [version]
- Technology: [symfony/flutter/etc.]

What I tried:
1. [step 1]
2. [step 2]

Error message:
[paste error]

Quick Fixes Checklist

When something doesn't work:

[ ] Restart Claude Code
[ ] Verify installation (ls .claude/)
[ ] Check file permissions
[ ] Validate configuration
[ ] Clear caches
[ ] Check dependencies (jq, yq)
[ ] Try reinstall with --force
[ ] Check documentation
[ ] Ask for help

← Tools Reference | Backlog Management →

Troubleshooting Guide ​

Table of Contents ​

Installation Issues ​

Commands Not Recognized After Installation ​

Files Not Found During Installation ​

Permission Denied Errors ​

Installation Creates Empty Directory ​

Agent Issues ​

Agent Not Available ​

Agent Gives Irrelevant Responses ​

Agent Conflicts with Project Rules ​

Command Issues ​

Command Not Found ​

Command Execution Errors ​

Command Output Incorrect ​

Configuration Issues ​

YAML Configuration Invalid ​

Project Not Found in Configuration ​

Configuration Not Applied ​

Tool Issues ​

StatusLine Not Displaying ​

MultiAccount Profile Issues ​

ProjectConfig yq Errors ​

Hook Issues ​

Hook Not Firing ​

PreCompact Hook Blocking ​

Sandbox Errors ​

Security-Related Hook Failures ​

Performance Issues ​

Slow Command Execution ​

Large Context Window Usage ​

Getting Help ​

Check Documentation ​

Get Version Info ​

Report Issues ​

Ask for Help ​

Quick Fixes Checklist ​

Troubleshooting Guide

Table of Contents

Installation Issues

Commands Not Recognized After Installation

Files Not Found During Installation

Permission Denied Errors

Installation Creates Empty Directory

Agent Issues

Agent Not Available

Agent Gives Irrelevant Responses

Agent Conflicts with Project Rules

Command Issues

Command Not Found

Command Execution Errors

Command Output Incorrect

Configuration Issues

YAML Configuration Invalid

Project Not Found in Configuration

Configuration Not Applied

Tool Issues

StatusLine Not Displaying

MultiAccount Profile Issues

ProjectConfig yq Errors

Hook Issues

Hook Not Firing

PreCompact Hook Blocking

Sandbox Errors

Security-Related Hook Failures

Performance Issues

Slow Command Execution

Large Context Window Usage

Getting Help

Check Documentation

Get Version Info

Report Issues

Ask for Help

Quick Fixes Checklist