06 troubleshooting common issues

Common Coherence APM v4.2.0 Issues and Solutions

This guide covers the most frequently encountered problems when using the Coherence - Agentic Persona Mapping (APM) Framework v4.2.0 and their proven solutions.

🚨 Most Common Issues

1. Coherence Command Not Recognized

Symptoms:

bash: /coherence: command not found
-bash: coherence: command not found
/coherence: No such file or directory
/coherence: command not found

Root Cause: Coherence native Claude Code slash commands are not properly installed or not in correct project directory.

Solution:

# Check Coherence APM installation
ls -la /mnt/c/Code/agentic-persona-mapping/.apm/

# Verify command files exist (67 total slash commands)
ls -la /mnt/c/Code/agentic-persona-mapping/.claude/commands/
ls /mnt/c/Code/agentic-persona-mapping/.claude/commands/ | wc -l  # Should show 67

# Check coherence command specifically
ls -la /mnt/c/Code/agentic-persona-mapping/.claude/commands/coherence.md

# Ensure you're in the correct directory
cd /mnt/c/Code/agentic-persona-mapping

Prevention:

Always run commands from /mnt/c/Code/agentic-persona-mapping directory
Ensure .claude/commands/ directory contains all 67 command files
Use /coherence as the primary activation command (not /coherence)

2. Persona Not Activating

Symptoms:

/developer command runs but persona doesn't activate
/analyst command runs but persona doesn't activate
No TTS voice notification plays
Agent behaves like regular Claude instead of persona

Root Cause: Session management files missing, TTS not configured, or missing persona files.

Solution:

# Check session notes directory
ls -la /mnt/c/Code/agentic-persona-mapping/.apm/session_notes/

# Check persona files (11 total personas)
ls -la /mnt/c/Code/agentic-persona-mapping/.apm/agents/personas/
ls /mnt/c/Code/agentic-persona-mapping/.apm/agents/personas/ | grep -E "\.(md)$" | wc -l

# Check voice scripts for TTS
ls -la /mnt/c/Code/agentic-persona-mapping/.apm/agents/voice/

# Test TTS voice script manually
bash /mnt/c/Code/agentic-persona-mapping/.apm/agents/voice/speakDeveloper.sh "Testing voice"
bash /mnt/c/Code/agentic-persona-mapping/.apm/agents/voice/speakOrchestrator.sh "Testing orchestrator"

# Check TTS providers (5 available: system, piper, elevenlabs, discord, none)
ls -la /mnt/c/Code/agentic-persona-mapping/.apm/agents/scripts/tts-providers/

Prevention:

Always use /coherence first to initialize the Coherence Orchestrator
Don't manually delete session files while agents are active
Ensure TTS provider is properly configured

3. Permission Denied Errors

Symptoms:

Permission denied: /mnt/c/Code/agentic-persona-mapping/.apm/session_notes/
bash: /mnt/c/Code/agentic-persona-mapping/.apm/agents/voice/speak*.sh: Permission denied
Cannot create file: Operation not permitted

Root Cause: Incorrect file permissions on Coherence APM directories or files.

Solution:

# Fix directory permissions
chmod -R 755 /mnt/c/Code/agentic-persona-mapping/.apm/
chmod +x /mnt/c/Code/agentic-persona-mapping/.apm/agents/voice/*.sh

# Fix session notes permissions
chmod 755 /mnt/c/Code/agentic-persona-mapping/.apm/session_notes/
chmod 644 /mnt/c/Code/agentic-persona-mapping/.apm/session_notes/*.md

# Fix command permissions
chmod 644 /mnt/c/Code/agentic-persona-mapping/.claude/commands/*.md

# Fix TTS provider scripts
chmod +x /mnt/c/Code/agentic-persona-mapping/.apm/agents/scripts/tts-providers/*.sh

Prevention:

Run Coherence native Claude Code slash commands from proper directory with appropriate permissions
Don't use sudo unless specifically required in WSL environment

4. TTS Voice Notifications Not Working

Symptoms:

Commands execute but no audio feedback
Silent operation when voice should play
"espeak not found" or TTS provider errors
Persona activation without voice confirmation

Root Cause: TTS provider not properly configured or installed.

Solution:

Check TTS Provider Configuration (5 providers available):

# Check available TTS providers
ls -la /mnt/c/Code/agentic-persona-mapping/.apm/agents/scripts/tts-providers/
# Should show: discord.sh, elevenlabs.sh, none.sh, piper.sh, system.sh

# Test system TTS provider (default)
bash /mnt/c/Code/agentic-persona-mapping/.apm/agents/scripts/tts-providers/system.sh "Test message"

# Test specific voice scripts
bash /mnt/c/Code/agentic-persona-mapping/.apm/agents/voice/speakOrchestrator.sh "Orchestrator test"
bash /mnt/c/Code/agentic-persona-mapping/.apm/agents/voice/speakDeveloper.sh "Developer test"
bash /mnt/c/Code/agentic-persona-mapping/.apm/agents/voice/speakAnalyst.sh "Analyst test"

Configure TTS System:

# For Linux/WSL - Install espeak
sudo apt-get install espeak espeak-data

# For macOS - Test built-in say command
say "Testing voice"

# For Windows/WSL - Use Piper TTS or configure system TTS
bash /mnt/c/Code/agentic-persona-mapping/.apm/agents/scripts/tts-providers/piper.sh "Test"

# If TTS fails, use none provider to disable
bash /mnt/c/Code/agentic-persona-mapping/.apm/agents/scripts/tts-providers/none.sh

Prevention:

Test TTS providers during Coherence APM setup
Configure fallback to 'none' provider for silent environments
Use Piper TTS for reliable cross-platform audio

5. Session Notes Not Found

Symptoms:

Cannot read session notes
Session context lost between commands
"No such file or directory" for session files
Coherence orchestrator fails to initialize

Root Cause: Session management directory structure missing or corrupted.

Solution:

# Check session structure
ls -la /mnt/c/Code/agentic-persona-mapping/.apm/session_notes/

# Check for existing sessions
ls -la /mnt/c/Code/agentic-persona-mapping/.apm/session_notes/*.md

# Check pre-compact archives
ls -la /mnt/c/Code/agentic-persona-mapping/.apm/session_notes/pre_compact_archive/

# Create new session with proper timestamp format
echo "# Coherence APM Session Recovery - $(date '+%Y-%m-%d %H:%M:%S')" > \
  "/mnt/c/Code/agentic-persona-mapping/.apm/session_notes/$(date '+%Y-%m-%d-%H-%M-%S')-Recovery-Session.md"

# Test Coherence initialization
cd /mnt/c/Code/agentic-persona-mapping
/coherence

Prevention:

Don't manually delete session directories
Use proper commands to manage sessions
Sessions are automatically archived by Coherence system

6. Agent Handoffs Failing

Symptoms:

/handoff command doesn't switch personas
/developer, /analyst, /architect commands fail to activate
Agents don't preserve context during handoffs
Multiple agents responding simultaneously

Root Cause: Session state corruption, improper persona activation, or missing persona files.

Solution:

# Check available personas (11 total)
ls -la /mnt/c/Code/agentic-persona-mapping/.apm/agents/personas/
ls /mnt/c/Code/agentic-persona-mapping/.apm/agents/personas/*.md | wc -l  # Should be 11+

# Check command availability (67 total slash commands)
ls /mnt/c/Code/agentic-persona-mapping/.claude/commands/*.md | wc -l  # Should be 67

# Test specific persona commands
cd /mnt/c/Code/agentic-persona-mapping
/developer  # Should activate Developer persona
/analyst    # Should activate Analyst persona
/architect  # Should activate Architect persona

# If handoff fails, restart Coherence
/coherence  # Primary orchestrator activation

Prevention:

Always use /coherence to initialize the orchestrator first
Use direct persona commands (/developer, /analyst, etc.) instead of /handoff
Ensure you're in the correct project directory

7. Performance Issues

Symptoms:

Commands take unusually long to execute
High CPU usage during simple operations
Memory usage grows over time
System becomes unresponsive

Root Cause: Resource leaks, large log files, or system constraints.

Solution:

# Check system resources
top -p $(pgrep -f apm)
df -h {{APM_ROOT}}

# Clean up large files
find {{APM_ROOT}}/session_notes/ -size +10M -ls
find {{APM_ROOT}}/logs/ -size +10M -delete

# Archive old sessions
mv {{APM_ROOT}}/session_notes/*.md {{APM_ROOT}}/session_notes/archive/

# Restart APM cleanly
/wrap
/coherence

Prevention:

Regularly archive old session notes
Monitor disk space usage
Use /wrap to clean up sessions periodically

8. Configuration Errors

Symptoms:

"Config file not found" errors
Environment variables not recognized
Path resolution failures

Root Cause: Missing or malformed configuration files.

Solution:

# Check configuration files
ls -la {{APM_ROOT}}/config/
cat {{APM_ROOT}}/config/apm.json

# Validate JSON configuration
python -m json.tool {{APM_ROOT}}/config/apm.json

# Reset to default configuration
cp {{APM_ROOT}}/config/apm.json.default {{APM_ROOT}}/config/apm.json

# Verify environment variables
env | grep APM
env | grep PROJECT

Prevention:

Always backup configuration files before editing
Use JSON validation tools when editing config files

9. Path Resolution Issues

Symptoms:

"No such file or directory" for existing files
Commands work in some directories but not others
Inconsistent behavior across different projects

Root Cause: Incorrect path configuration or environment variables.

Solution:

# Check current paths
echo "APM_ROOT: $APM_ROOT"
echo "PROJECT_ROOT: $PROJECT_ROOT"
echo "PWD: $(pwd)"

# Verify path variables in configuration
grep -r "APM_ROOT\|PROJECT_ROOT" {{APM_ROOT}}/config/

# Reset paths
export APM_ROOT="{{APM_ROOT}}"
export PROJECT_ROOT="{{PROJECT_ROOT}}"

# Test path resolution
ls -la $APM_ROOT/agents/
ls -la $PROJECT_ROOT/.apm/

Prevention:

Set environment variables in your shell profile
Use absolute paths in configuration files

10. Git Integration Issues

Symptoms:

native Claude Code slash commands don't respect .gitignore
Session notes accidentally committed
Permission conflicts with git operations

Root Cause: Incorrect .gitignore configuration or file permissions.

Solution:

# Check .gitignore
cat {{PROJECT_ROOT}}/.gitignore | grep -E "(apm|session|\.apm)"

# Add APM exclusions
echo ".apm/session_notes/*.md" >> {{PROJECT_ROOT}}/.gitignore
echo ".apm/state/" >> {{PROJECT_ROOT}}/.gitignore

# Remove accidentally committed files
git rm --cached .apm/session_notes/*.md
git commit -m "Remove APM session files from git"

# Fix permissions
chmod 644 {{PROJECT_ROOT}}/.gitignore

Prevention:

Configure .gitignore before first APM use
Keep session notes and temporary files out of version control

🔍 Diagnostic Commands

Quick Health Check

# APM structure validation
ls -la {{APM_ROOT}}/agents/ {{APM_ROOT}}/session_notes/ {{PROJECT_ROOT}}/.apm/

# Permission check
find {{APM_ROOT}} -type f -name "*.sh" -not -executable

# Configuration validation
python -m json.tool {{APM_ROOT}}/config/apm.json >/dev/null && echo "Config OK"

Environment Verification

# Environment variables
env | grep -E "(APM|PROJECT)_ROOT"

# Path accessibility
[ -d "$APM_ROOT" ] && echo "APM_ROOT accessible" || echo "APM_ROOT missing"
[ -d "$PROJECT_ROOT" ] && echo "PROJECT_ROOT accessible" || echo "PROJECT_ROOT missing"

# Command availability
which espeak 2>/dev/null && echo "espeak available"
which say 2>/dev/null && echo "say available"

Log Analysis

# Check for recent errors
tail -n 50 {{APM_ROOT}}/logs/apm.log | grep -i error

# Session management logs
ls -lt {{APM_ROOT}}/session_notes/ | head -5

# Voice script logs (if available)
tail -n 20 {{APM_ROOT}}/logs/voice.log

🆘 When to Escalate

Contact support or check advanced troubleshooting if:

Multiple solutions from this guide don't resolve the issue
You encounter data corruption or loss
Security-related errors appear
System-wide impacts are observed
The problem affects multiple users or projects

📚 Related Resources

Installation Issues - Setup and deployment problems
Performance Issues - System performance optimization
Agent Issues - Agent-specific troubleshooting
Diagnostic Tools - Advanced debugging utilities

Last Updated: 2025-08-19 Coherence APM Framework v4.2.0 - Enhanced TTS Audio Experience

06 troubleshooting common issues

Common Coherence APM v4.2.0 Issues and Solutions

🚨 Most Common Issues

1. Coherence Command Not Recognized

2. Persona Not Activating

3. Permission Denied Errors

4. TTS Voice Notifications Not Working

5. Session Notes Not Found

6. Agent Handoffs Failing

7. Performance Issues

8. Configuration Errors

9. Path Resolution Issues

10. Git Integration Issues

🔍 Diagnostic Commands

Quick Health Check

Environment Verification

Log Analysis

🆘 When to Escalate

📚 Related Resources

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Clone this wiki locally