TROUBLESHOOTING.md

RuVector Hooks Troubleshooting Guide

Solutions for common issues with the RuVector hooks system.

Table of Contents

1. Quick Diagnostics
2. Installation Issues
3. Hook Execution Issues
4. Intelligence Layer Issues
5. Performance Issues
6. Platform-Specific Issues
7. Migration Issues
8. Debug Mode

---

Quick Diagnostics

Run Full Diagnostic

# Check overall health
npx ruvector hooks stats --verbose

# Validate configuration
npx ruvector hooks validate-config

# Test hook execution
npx ruvector hooks pre-edit --file test.ts
npx ruvector hooks post-edit --file test.ts --success true

Common Symptoms and Solutions

Symptom	Likely Cause	Solution
Hooks not running	Missing settings.json	Run hooks install
"Command not found"	CLI not in PATH	Use npx ruvector
No agent assignment	Intelligence disabled	Set RUVECTOR_INTELLIGENCE_ENABLED=true
Slow hook execution	Large memory	Clean old trajectories
Windows errors	Shell mismatch	Check shell wrapper

---

Installation Issues

Problem: hooks init fails

Symptoms:

Error: Failed to create .ruvector directory
Permission denied

Solutions:

1. Check directory permissions:

ls -la .
# Ensure you have write access

2. Create directory manually:

mkdir -p .ruvector/intelligence
npx ruvector hooks init

3. Use sudo (last resort):

sudo npx ruvector hooks init
sudo chown -R $USER:$USER .ruvector

---

Problem: hooks install doesn't update settings

Symptoms:

• .claude/settings.json unchanged
• Old hooks still running

Solutions:

1. Use --force flag:

npx ruvector hooks install --force

2. Check backup and restore:

# View backup
cat .claude/settings.json.backup

# If needed, restore and try again
cp .claude/settings.json.backup .claude/settings.json
npx ruvector hooks install --force

3. Manually edit settings:

# Open and verify hook section
code .claude/settings.json

---

Problem: "npx ruvector" command not found

Symptoms:

npm ERR! could not determine executable to run

Solutions:

1. Install globally:

npm install -g @ruvector/cli
ruvector hooks init

2. Check npm configuration:

npm config get prefix
# Ensure this is in your PATH

3. Use npx with package:

npx @ruvector/cli hooks init

---

Hook Execution Issues

Problem: Hooks not triggering

Symptoms:

• No output when editing files
• Session start message missing
• Intelligence not active

Diagnosis:

# Check settings.json has hooks
cat .claude/settings.json | jq '.hooks'

# Should show PreToolUse, PostToolUse, etc.

Solutions:

1. Reinstall hooks:

npx ruvector hooks install --force

2. Check matcher patterns:

{
  "hooks": {
    "PreToolUse": [{
      "matcher": "Bash",  // Case-sensitive!
      "hooks": [...]
    }]
  }
}

3. Verify Claude Code is loading settings:

# Restart Claude Code to reload settings

---

Problem: Hook timeout

Symptoms:

Warning: Hook timeout after 3000ms

Solutions:

1. Increase timeout in settings:

{
  "hooks": {
    "PreToolUse": [{
      "matcher": "Bash",
      "hooks": [{
        "timeout": 5000,  // Increase to 5 seconds
        "command": "..."
      }]
    }]
  }
}

2. Check for slow operations:

# Time hook execution
time npx ruvector hooks pre-edit --file test.ts

3. Reduce hook complexity:

• Disable neural training in pre-hooks
• Use async for heavy operations
• Cache repeated lookups

---

Problem: Hook blocks tool execution

Symptoms:

• Edit operations not completing
• "continue: false" in output

Diagnosis:

# Test hook directly
npx ruvector hooks pre-edit --file problematic-file.ts

# Check response
# { "continue": false, "reason": "..." }

Solutions:

1. Check protected files:

# If file is protected, you'll see:
# { "continue": false, "reason": "Protected file" }

# Add to exceptions in config.toml
[hooks]
protected_exceptions = [".env.local"]

2. Disable blocking:

{
  "hooks": {
    "PreToolUse": [{
      "matcher": "Write",
      "hooks": [{
        "command": "...",
        "continueOnError": true  // Never block on error
      }]
    }]
  }
}

---

Intelligence Layer Issues

Problem: No agent suggestions

Symptoms:

• assignedAgent always null
• No intelligence guidance

Diagnosis:

# Check intelligence status
npx ruvector hooks stats

# Expected output:
# Patterns: N
# Memories: N
# Status: Ready

Solutions:

1. Enable intelligence:

export RUVECTOR_INTELLIGENCE_ENABLED=true

2. Check data files exist:

ls -la .ruvector/intelligence/
# Should show patterns.json, memory.json, etc.

3. Initialize fresh data:

npx ruvector hooks init --force

---

Problem: Poor agent suggestions

Symptoms:

• Wrong agent assigned to file types
• Low confidence scores

Diagnosis:

# Check patterns
npx ruvector hooks stats --verbose

# Look for:
# Top Patterns:
#   1. edit_rs_in_xxx → rust-developer (Q=0.82)

Solutions:

1. Reset learning data:

rm .ruvector/intelligence/patterns.json
rm .ruvector/intelligence/trajectories.json
# Will rebuild from scratch

2. Import team patterns:

npx ruvector hooks import --input team-patterns.json

3. Wait for learning:

• Patterns improve with use
• 50+ edits needed for good suggestions

---

Problem: Memory search slow or failing

Symptoms:

• Memory search timeout
• "Error: Failed to load memory"

Diagnosis:

# Check memory size
ls -la .ruvector/intelligence/memory.json

# If >10MB, consider cleanup

Solutions:

1. Clean old memories:

# Backup first
cp .ruvector/intelligence/memory.json memory-backup.json

# Keep only recent
node -e "
const fs = require('fs');
const data = JSON.parse(fs.readFileSync('.ruvector/intelligence/memory.json'));
const recent = data.slice(-1000);  // Keep last 1000
fs.writeFileSync('.ruvector/intelligence/memory.json', JSON.stringify(recent));
"

2. Rebuild HNSW index:

rm .ruvector/intelligence/memory.rvdb
# Will rebuild on next use

---

Performance Issues

Problem: High hook overhead

Symptoms:

• Slow file operations
• Noticeable delay on every edit

Diagnosis:

# Time individual hooks
time npx ruvector hooks pre-edit --file test.ts
time npx ruvector hooks post-edit --file test.ts --success true

# Target: <50ms each

Solutions:

1. Disable neural training:

# In config.toml
[intelligence]
neural_training = false

2. Reduce memory operations:

[hooks]
store_memory = false  # Disable memory storage

3. Use async post-hooks:

{
  "hooks": {
    "PostToolUse": [{
      "matcher": "Write",
      "hooks": [{
        "command": "...",
        "async": true  // Don't wait for completion
      }]
    }]
  }
}

---

Problem: Large intelligence data files

Symptoms:

• .ruvector/intelligence/ >100MB
• Slow startup

Solutions:

1. Set retention limits:

# In config.toml
[intelligence]
max_trajectories = 1000
max_memories = 10000

2. Clean old data:

# Export current patterns
npx ruvector hooks export --output patterns-backup.json --include patterns

# Reset
rm -rf .ruvector/intelligence/*

# Re-import patterns
npx ruvector hooks import --input patterns-backup.json

---

Platform-Specific Issues

Windows Issues

Problem: "/bin/bash not found"

Symptoms:

'/bin/bash' is not recognized as an internal or external command

Solution:

Check that hooks use Windows-compatible shell:

{
  "hooks": {
    "PreToolUse": [{
      "matcher": "Bash",
      "hooks": [{
        "command": "cmd /c 'npx ruvector hooks pre-command'"
      }]
    }]
  }
}

Or reinstall hooks (auto-detects platform):

npx ruvector hooks install --force

Problem: Path separator issues

Symptoms:

• File paths not recognized
• "File not found" errors

Solution:

Ensure paths use forward slashes or escaped backslashes:

# Good
npx ruvector hooks pre-edit --file "src/app.ts"

# Bad on Windows
npx ruvector hooks pre-edit --file "src\app.ts"

Problem: jq not found

Symptoms:

'jq' is not recognized as an internal or external command

Solutions:

1. Install jq:

# Using chocolatey
choco install jq

# Using scoop
scoop install jq

2. Or use jq-free hooks:

npx ruvector hooks install --template minimal

---

macOS Issues

Problem: Permission denied

Symptoms:

Error: EACCES: permission denied

Solutions:

1. Fix npm permissions:

sudo chown -R $(whoami) ~/.npm

2. Use nvm:

# Install nvm and use it for npm
nvm install node
nvm use node

---

Linux Issues

Problem: Node.js version too old

Symptoms:

SyntaxError: Unexpected token '.'

Solution:

Update Node.js:

# Using nvm
nvm install 18
nvm use 18

# Or using package manager
curl -fsSL https://deb.nodesource.com/setup_18.x | sudo -E bash -
sudo apt-get install -y nodejs

---

Migration Issues

Problem: Migration data loss

Symptoms:

• Fewer patterns after migration
• Missing memories

Diagnosis:

# Compare counts
echo "Before: $(jq '.length' old-patterns.json)"
echo "After: $(npx ruvector hooks stats --json | jq '.patterns')"

Solutions:

1. Use validation:

npx ruvector hooks migrate --from old-data --validate

2. Merge instead of replace:

npx ruvector hooks migrate --from old-data --merge

3. Restore from backup:

cp .ruvector/intelligence/backup-*/* .ruvector/intelligence/

---

Problem: SQLite migration format error

Symptoms:

Error: Unknown embedding format in memory.db

Solution:

SQLite migration requires format detection. For MVP, use JSON export:

# Export from source as JSON first
npx claude-flow memory export --output memory.json

# Then import
npx ruvector hooks import --input memory.json

---

Debug Mode

Enable Debug Output

# Set environment variable
export CLAUDE_FLOW_DEBUG=true
export RUVECTOR_DEBUG=true

# Run with debug
npx ruvector hooks pre-edit --file test.ts --debug

Debug Output Interpretation

DEBUG: Loading config from .ruvector/config.toml
DEBUG: Intelligence enabled: true
DEBUG: Q-table loaded: 89 patterns
DEBUG: Memory loaded: 543 vectors
DEBUG: Encoding state for test.ts
DEBUG: State key: edit_ts_in_project
DEBUG: Q-values: { "typescript-developer": 0.82, "coder": 0.45 }
DEBUG: Selected agent: typescript-developer (confidence: 0.82)

View Hook Logs

# Today's logs
cat .ruvector/logs/hooks-$(date +%Y-%m-%d).log

# Tail logs
tail -f .ruvector/logs/hooks-*.log

Test Hooks Manually

# Test pre-edit
echo '{"tool_input":{"file_path":"test.ts"}}' | npx ruvector hooks pre-edit --stdin

# Test post-edit
echo '{"tool_input":{"file_path":"test.ts"},"tool_result":{"success":true}}' | npx ruvector hooks post-edit --stdin

---

Getting Help

Gather Diagnostic Info

# Create diagnostic report
{
  echo "=== RuVector Version ==="
  npx ruvector --version

  echo -e "\n=== Node Version ==="
  node --version

  echo -e "\n=== Platform ==="
  uname -a

  echo -e "\n=== Hooks Stats ==="
  npx ruvector hooks stats --json

  echo -e "\n=== Config ==="
  cat .ruvector/config.toml

  echo -e "\n=== Settings ==="
  cat .claude/settings.json | jq '.hooks'
} > ruvector-diagnostic.txt

echo "Diagnostic saved to ruvector-diagnostic.txt"

Report Issues

1. Create diagnostic report (above)
2. Open issue: https://github.com/ruvnet/ruvector/issues
3. Include:
   • Diagnostic report
   • Steps to reproduce
   • Expected vs actual behavior

---

See Also

• User Guide - Getting started
• CLI Reference - Command documentation
• Architecture - Technical details
• Migration Guide - Upgrade from other systems