Skip to content

06 troubleshooting installation issues

Jump to bottom
Doug Beard edited this page Aug 20, 2025 · 2 revisions

Coherence APM v4.2.0 Installation Issues and Solutions

This guide addresses problems encountered during Coherence APM Framework v4.2.0 installation and initial setup.

🚀 Pre-Installation Requirements

System Prerequisites

Before troubleshooting, verify these requirements are met:

Required:

  • Claude Code CLI installed and functional
  • Bash shell (Linux/macOS/WSL)
  • Git (for version control integration)
  • Write permissions in /mnt/c/Code/agentic-persona-mapping directory

Optional but Recommended:

  • TTS support (5 providers: system, piper, elevenlabs, discord, none)
  • Python 3.x (for scripts and validation)
  • WSL environment for Windows users

Environment Check

# Verify Claude Code
claude --version

# Check shell
echo $SHELL
bash --version

# Check Git
git --version

# Check TTS providers (5 available)
ls /mnt/c/Code/agentic-persona-mapping/.apm/agents/scripts/tts-providers/ 2>/dev/null || echo "TTS providers not found"

# Test TTS functionality
bash /mnt/c/Code/agentic-persona-mapping/.apm/agents/scripts/tts-providers/system.sh "Test" 2>/dev/null || echo "System TTS not available"

# Check Python (optional)
python3 --version 2>/dev/null || python --version 2>/dev/null || echo "Python not found"

🔧 Installation Failures

1. Coherence APM Not Found or Incorrectly Installed

Symptoms:

/coherence: command not found
.apm directory missing
.claude/commands directory missing
67 command files not found

Root Cause: Coherence APM not properly installed or wrong directory.

Solution:

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

# Check Coherence APM structure
ls -la .apm/
ls -la .claude/commands/

# Verify all 67 slash commands are installed
ls .claude/commands/*.md | wc -l  # Should return 67

# Check coherence command specifically
ls -la .claude/commands/coherence.md

# Verify persona files (11 personas)
ls .apm/agents/personas/*.md | wc -l  # Should return 11+

# Check TTS providers (5 providers)
ls .apm/agents/scripts/tts-providers/*.sh | wc -l  # Should return 5

If Structure Missing:

# Clone the repository if missing
git clone https://github.com/your-org/agentic-persona-mapping.git /mnt/c/Code/agentic-persona-mapping
cd /mnt/c/Code/agentic-persona-mapping

# Test coherence command
/coherence

2. Permission Denied During Installation

Symptoms:

mkdir: cannot create directory '.apm': Permission denied
cp: cannot create regular file: Permission denied
chmod: cannot access files: Permission denied

Root Cause: Insufficient write permissions in Coherence APM directory.

Solution:

Fix Permissions for WSL Environment:

# Navigate to Coherence APM directory
cd /mnt/c/Code/agentic-persona-mapping

# Fix directory permissions
chmod 755 .apm/ .claude/
chmod -R 755 .apm/agents/
chmod -R 755 .claude/commands/

# Fix script permissions
chmod +x .apm/agents/voice/*.sh
chmod +x .apm/agents/scripts/tts-providers/*.sh

# Verify permissions
ls -la .apm/
ls -la .claude/

For Git Repository Management:

# If using git, fix ownership
sudo chown -R $USER:$USER /mnt/c/Code/agentic-persona-mapping

# Set proper git permissions
git config core.fileMode false  # Disable file mode changes in git

WSL-Specific Solutions:

# Mount with proper permissions (add to /etc/wsl.conf)
# [automount]
# options = "metadata,umask=22,fmask=11"

# Restart WSL after configuration change
wsl --shutdown
# Restart WSL

3. Incomplete Installation

Symptoms:

Installation appears successful but commands don't work
Missing files or directories after installation
"APM not properly configured" errors

Root Cause: Partial installation due to interrupted process or missing dependencies.

Solution:

# Check installation completeness
ls -la {{APM_ROOT}}/
ls -la {{APM_ROOT}}/agents/
ls -la {{APM_ROOT}}/config/
ls -la {{PROJECT_ROOT}}/.claude/commands/

# Identify missing components
if [ ! -d "{{APM_ROOT}}/agents" ]; then
    echo "Missing: Agent definitions"
fi
if [ ! -d "{{APM_ROOT}}/session_notes" ]; then
    echo "Missing: Session management"
fi
if [ ! -f "{{PROJECT_ROOT}}/.claude/commands/coherence.md" ]; then
    echo "Missing: Command definitions"
fi

# Reinstall with force flag
./install.sh --force --clean-install

# Verify installation
{{APM_ROOT}}/scripts/verify-installation.sh

4. Path Configuration Issues

Symptoms:

APM_ROOT or PROJECT_ROOT not set correctly
Commands reference wrong paths
"Configuration path not found" errors

Root Cause: Environment variables not set or incorrectly configured.

Solution:

# Check current environment
echo "APM_ROOT: ${APM_ROOT:-'NOT SET'}"
echo "PROJECT_ROOT: ${PROJECT_ROOT:-'NOT SET'}"

# Set correct paths
export APM_ROOT="{{APM_ROOT}}"
export PROJECT_ROOT="{{PROJECT_ROOT}}"

# Make permanent (add to shell profile)
echo 'export APM_ROOT="{{APM_ROOT}}"' >> ~/.bashrc
echo 'export PROJECT_ROOT="{{PROJECT_ROOT}}"' >> ~/.bashrc
source ~/.bashrc

# Alternative: Use installer with explicit paths
./install.sh --apm-root "{{APM_ROOT}}" --project-root "{{PROJECT_ROOT}}"

5. Claude Code Integration Failure

Symptoms:

APM installs but Claude Code doesn't recognize commands
/coherence command not found in Claude Code
Commands exist but don't execute properly

Root Cause: Claude Code command directory not properly configured.

Solution:

# Check Claude Code configuration
cat ~/.claude/config.json | grep -A 5 -B 5 commands

# Verify command files are in correct location
ls -la {{PROJECT_ROOT}}/.claude/commands/

# Check command file format
head -5 {{PROJECT_ROOT}}/.claude/commands/coherence.md

# Reinstall Claude Code integration
./install.sh --claude-integration-only

# Test Claude Code recognition
cd {{PROJECT_ROOT}}
claude --help | grep -i commands

6. Dependency Installation Issues

Symptoms:

"espeak not found" during voice setup
Missing Python modules for configuration
JSON parsing errors

Root Cause: System dependencies not installed or not in PATH.

Solution:

Linux (Ubuntu/Debian):

sudo apt-get update
sudo apt-get install espeak espeak-data
sudo apt-get install python3 python3-json
sudo apt-get install jq curl wget

Linux (CentOS/RHEL):

sudo yum install espeak espeak-data
sudo yum install python3
sudo yum install jq curl wget

macOS:

# Text-to-speech is built-in (say command)
# Install optional tools
brew install jq curl wget python3

Windows/WSL:

# Install Linux dependencies in WSL
sudo apt-get install espeak
# For native Windows TTS, voice notifications may be limited

7. Version Conflicts

Symptoms:

"Incompatible APM version" warnings
Mixed version files after upgrade
Commands behave inconsistently

Root Cause: Previous APM installation not properly removed before new installation.

Solution:

# Backup existing configuration
cp -r {{APM_ROOT}}/config {{APM_ROOT}}/config.backup
cp -r {{APM_ROOT}}/session_notes {{APM_ROOT}}/session_notes.backup

# Complete uninstall
./uninstall.sh --complete-removal
# or manually:
rm -rf {{APM_ROOT}}
rm -rf {{PROJECT_ROOT}}/.claude/commands/coherence*.md
rm -rf {{PROJECT_ROOT}}/.claude/commands/parallel*.md

# Clean install
./install.sh --clean-install

# Restore configuration if needed
cp -r {{APM_ROOT}}/config.backup/* {{APM_ROOT}}/config/

8. Network Installation Issues

Symptoms:

Download timeouts during installation
"Cannot resolve host" errors
Partial downloads or corrupted files

Root Cause: Network connectivity, firewall, or proxy issues.

Solution:

# Test network connectivity
ping -c 3 github.com
curl -I https://github.com

# Check proxy settings
echo "HTTP_PROXY: ${HTTP_PROXY:-'not set'}"
echo "HTTPS_PROXY: ${HTTPS_PROXY:-'not set'}"

# Download manually if automated download fails
wget https://github.com/example/apm-framework/archive/main.zip
unzip main.zip
cd apm-framework-main/installer/
./install.sh --offline-install

# Or use local installation
git clone https://github.com/example/apm-framework.git
cd apm-framework/installer/
./install.sh --local-install

🔍 Installation Verification

Automatic Verification

# Run built-in verification script
{{APM_ROOT}}/scripts/verify-installation.sh

# Check installation health
{{APM_ROOT}}/scripts/health-check.sh

Manual Verification Checklist

Directory Structure:

# Required directories exist
[ -d "{{APM_ROOT}}" ] && echo "✓ APM root exists" || echo "✗ APM root missing"
[ -d "{{APM_ROOT}}/agents" ] && echo "✓ Agents directory exists" || echo "✗ Agents directory missing"
[ -d "{{APM_ROOT}}/session_notes" ] && echo "✓ Session notes directory exists" || echo "✗ Session notes directory missing"
[ -d "{{APM_ROOT}}/config" ] && echo "✓ Config directory exists" || echo "✗ Config directory missing"

Command Integration:

# Claude Code commands installed
[ -f "{{PROJECT_ROOT}}/.claude/commands/coherence.md" ] && echo "✓ AP command installed" || echo "✗ AP command missing"
[ -f "{{PROJECT_ROOT}}/.claude/commands/dev.md" ] && echo "✓ Developer command installed" || echo "✗ Developer command missing"

Permissions:

# Executable permissions
[ -x "{{APM_ROOT}}/agents/voice/speakOrchestrator.sh" ] && echo "✓ Voice scripts executable" || echo "✗ Voice scripts not executable"
[ -w "{{APM_ROOT}}/session_notes" ] && echo "✓ Session notes writable" || echo "✗ Session notes not writable"

Configuration:

# Valid configuration files
python3 -m json.tool {{APM_ROOT}}/config/apm.json >/dev/null 2>&1 && echo "✓ Configuration valid" || echo "✗ Configuration invalid"

Test Installation

# Test basic APM functionality
cd {{PROJECT_ROOT}}
echo "Testing basic APM activation..."

# This should work without errors
/coherence --test-mode

# Check for proper session creation
ls -la {{APM_ROOT}}/session_notes/ | tail -3

🚨 Emergency Recovery

Complete Reinstallation

If installation is severely corrupted:

# 1. Stop all APM processes
pkill -f apm

# 2. Backup user data
mkdir -p ~/apm-backup/$(date +%Y%m%d)
cp -r {{APM_ROOT}}/session_notes ~/apm-backup/$(date +%Y%m%d)/
cp -r {{APM_ROOT}}/config ~/apm-backup/$(date +%Y%m%d)/

# 3. Complete removal
rm -rf {{APM_ROOT}}
rm -rf {{PROJECT_ROOT}}/.claude/commands/coherence*.md
rm -rf {{PROJECT_ROOT}}/.claude/commands/parallel*.md

# 4. Fresh installation
./install.sh --clean-install --force

# 5. Restore user data (optional)
cp -r ~/apm-backup/$(date +%Y%m%d)/session_notes/* {{APM_ROOT}}/session_notes/
cp ~/apm-backup/$(date +%Y%m%d)/config/user-config.json {{APM_ROOT}}/config/

📋 Pre-Installation Checklist

Before installing APM, verify:

  • Claude Code is installed and working
  • You have write permissions in the target directory
  • Network connectivity is available (for downloads)
  • Required disk space is available (minimum 100MB)
  • Bash shell is available and functional
  • Git is installed (recommended)
  • Text-to-speech is available (optional but recommended)

🔧 Custom Installation Options

Silent Installation

# Unattended installation
./install.sh --silent --defaults

# With custom configuration
./install.sh --silent --config ./custom-config.json

Development Installation

# Install in development mode
./install.sh --dev-mode --verbose

# Install with debugging enabled
./install.sh --debug --log-file installation.log

Enterprise Installation

# System-wide installation
sudo ./install.sh --system-install --shared-config

# Multi-user installation
./install.sh --multi-user --permissions 755

📚 Related Resources

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

Clone this wiki locally