proffesor-for-testing__agentic-qe/docs/TROUBLESHOOTING.md

Agentic QE Fleet - Troubleshooting Guide

Quick Diagnosis

Start here to quickly identify your issue:

# Run system diagnostics
aqe diagnostics

# Check fleet health
aqe status --verbose

# View recent logs
tail -f ~/.agentic-qe/logs/aqe.log

Common Issues

Installation Issues

Issue: npm install fails with permission errors

Symptoms:

npm ERR! Error: EACCES: permission denied

Solutions:

Option 1: Use npx (Recommended)

npx agentic-qe init

Option 2: Fix npm permissions

# Fix npm global permissions
mkdir ~/.npm-global
npm config set prefix '~/.npm-global'
echo 'export PATH=~/.npm-global/bin:$PATH' >> ~/.bashrc
source ~/.bashrc

# Reinstall
npm install -g agentic-qe

Option 3: Use sudo (Not Recommended)

sudo npm install -g agentic-qe

Issue: Node.js version incompatibility

Symptoms:

error agentic-qe@1.0.0: The engine "node" is incompatible with this module

Solution:

# Check Node.js version
node --version  # Should be >= 18.0.0

# Upgrade Node.js using nvm
nvm install 18
nvm use 18
nvm alias default 18

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

# macOS
brew install node@18

Issue: TypeScript compilation errors

Symptoms:

TSError: Unable to compile TypeScript

Solution:

# Clear cache and rebuild
npm cache clean --force
rm -rf node_modules
npm install
npm run build

Agent Execution Issues

Issue: Agent fails to start

Symptoms:

Error: Agent failed to start: timeout
Error: Agent initialization failed

Diagnostic Steps:

# 1. Check system resources
free -h  # Check available memory
top      # Check CPU usage

# 2. Check configuration
aqe config show | grep maxAgents

# 3. Check agent status
aqe fleet status --verbose

Solutions:

Solution 1: Reduce concurrent agents

aqe config set --key fleet.maxAgents --value 10

Solution 2: Increase timeouts

aqe config set --key agent.timeout --value 600000

Solution 3: Check memory limits

# Increase Node.js memory
NODE_OPTIONS="--max-old-space-size=4096" aqe execute

Issue: Agent stuck in "busy" state

Symptoms:

• Agent shows as "busy" but no progress
• Commands timeout waiting for agent

Diagnostic:

# Check agent status
aqe fleet status

# View agent logs
aqe logs --agent-id <agent-id> --tail 100

Solutions:

Solution 1: Restart stuck agent

aqe agent restart --agent-id <agent-id>

Solution 2: Kill and respawn agent

aqe agent kill --agent-id <agent-id>
aqe agent spawn --type test-generator

Solution 3: Reset fleet state

aqe fleet reset
aqe init

Test Generation Issues

Issue: No tests generated

Symptoms:

• aqe test completes but no test files created
• Error: "No testable code found"

Diagnostic:

# Run with verbose logging
aqe test src/service.ts --verbose

# Check file path
ls -la src/service.ts

# Check file content
cat src/service.ts

Solutions:

Solution 1: Verify file is exportable

// File must export functions/classes
export function myFunction() { /* ... */ }
export class MyClass { /* ... */ }

Solution 2: Check file extension

# Supported extensions: .ts, .tsx, .js, .jsx
aqe test src/service.ts    # ✓ Correct
aqe test src/service.py    # ✗ Not supported

Solution 3: Specify framework

aqe test src/service.ts --framework jest

Issue: Generated tests are incorrect

Symptoms:

• Tests fail immediately
• Tests don't match code structure
• Missing important test cases

Solutions:

Solution 1: Regenerate with higher coverage

aqe test src/service.ts --coverage 95 --regenerate

Solution 2: Specify test style

aqe test src/service.ts --style property-based

Solution 3: Review and manually adjust

# Generated tests are starting points
# Review and adjust in tests/ directory

MCP Integration Issues

Issue: Claude Code can't connect to MCP server

Symptoms:

Error: Cannot connect to MCP server
Error: MCP server not found

Diagnostic:

# Check if MCP server is registered
claude mcp list

# Check MCP server logs
cat ~/.claude/logs/mcp-agentic-qe.log

Solutions:

Solution 1: Add MCP server

# Add MCP server to Claude Code
claude mcp add agentic-qe npx -y agentic-qe mcp:start

# Verify addition
claude mcp list | grep agentic-qe

Solution 2: Restart Claude Code

# Restart Claude Code application
# Then verify connection
claude mcp list

Solution 3: Manually start MCP server

# Start MCP server directly
npx agentic-qe mcp:start

# In another terminal, verify
curl http://localhost:3000/health

Issue: MCP tools not appearing in Claude Code

Symptoms:

• MCP server connected but tools not available
• Error: "Unknown tool: mcp__agentic_qe__..."

Solutions:

Solution 1: Restart Claude Code and refresh

# 1. Restart Claude Code
# 2. In Claude Code: /mcp list
# 3. Verify tools are listed

Solution 2: Check MCP server version

aqe --version  # Should be >= 1.0.0
npm update -g agentic-qe

Solution 3: Re-add MCP server

claude mcp remove agentic-qe
claude mcp add agentic-qe npx -y agentic-qe mcp:start

Memory and Performance Issues

Issue: High memory usage

Symptoms:

Error: JavaScript heap out of memory
Process consuming > 4GB RAM

Diagnostic:

# Check memory usage
ps aux | grep agentic-qe
top -p $(pgrep -f agentic-qe)

# Check fleet status
aqe fleet status --memory

Solutions:

Solution 1: Reduce parallel workers

aqe execute --workers 1

Solution 2: Execute tests in batches

# Instead of running all at once
aqe execute tests/unit/
aqe execute tests/integration/

Solution 3: Increase Node.js memory limit

# Temporary
NODE_OPTIONS="--max-old-space-size=4096" aqe execute

# Permanent (add to .bashrc or .zshrc)
export NODE_OPTIONS="--max-old-space-size=4096"

Solution 4: Enable garbage collection

NODE_OPTIONS="--expose-gc --max-old-space-size=2048" aqe execute

Issue: Slow test execution

Symptoms:

• Tests take much longer than expected
• Fleet appears unresponsive

Diagnostic:

# Check fleet performance
aqe fleet monitor --interval 1s

# Check agent distribution
aqe fleet status --agents

Solutions:

Solution 1: Enable parallel execution

aqe execute --parallel --workers 4

Solution 2: Optimize test selection

aqe execute --optimize --coverage-threshold 90

Solution 3: Increase agent count

aqe config set --key fleet.maxAgents --value 30

Coverage Analysis Issues

Issue: Coverage report shows 0%

Symptoms:

Coverage: 0.00%
No coverage data collected

Diagnostic:

# Check if tests ran
aqe execute --coverage --verbose

# Check coverage configuration
cat .agentic-qe/config.json | grep coverage

Solutions:

Solution 1: Ensure tests execute successfully

# Run tests first
aqe execute
# Then run coverage
aqe coverage

Solution 2: Check coverage tool configuration

# Verify jest.config.js or similar
cat jest.config.js | grep coverage

Solution 3: Specify coverage tool

aqe coverage --tool jest

Issue: Coverage gaps not detected

Symptoms:

• Coverage analyzer completes but reports no gaps
• Expected uncovered lines not reported

Solution:

# Run with detailed gap analysis
aqe coverage --analysis comprehensive --threshold 95

Quality Gate Issues

Issue: Quality gate always fails

Symptoms:

Quality gate: FAILED
All checks failing despite good metrics

Diagnostic:

# View quality gate results
aqe quality --verbose

# Check thresholds
aqe config get --key agents.quality-gate.config.thresholds

Solutions:

Solution 1: Adjust thresholds

aqe quality --coverage 80 --complexity 15

Solution 2: View detailed report

aqe quality --report detailed --export report.json
cat report.json | jq .

Solution 3: Skip specific checks

aqe quality --skip security --coverage 85

Database Issues

Issue: SQLite database locked

Symptoms:

Error: SQLITE_BUSY: database is locked

Solutions:

Solution 1: Close other connections

# Stop all AQE processes
pkill -f agentic-qe

# Restart
aqe init

Solution 2: Reset database

# Backup first
cp data/fleet.db data/fleet.db.backup

# Reset
rm data/fleet.db
aqe init

Solution 3: Increase timeout

# In .agentic-qe/config.json
{
  "database": {
    "timeout": 10000
  }
}

Error Messages Reference

Common Error Codes

Error Code	Meaning	Solution
AQE_001	Fleet initialization failed	Run aqe init again
AQE_002	Agent spawn timeout	Increase timeout or reduce agents
AQE_003	Test generation failed	Check source file is valid
AQE_004	Coverage analysis failed	Ensure tests ran successfully
AQE_005	Quality gate blocked	Review quality metrics
AQE_006	Memory limit exceeded	Increase memory or reduce workers
AQE_007	Database error	Check database connection
AQE_008	Configuration invalid	Validate configuration file
AQE_009	MCP connection failed	Restart MCP server
AQE_010	Agent coordination failed	Reset fleet state

Error Message Examples

"Agent failed to start: timeout"

# Cause: Agent took too long to initialize
# Solution:
aqe config set --key agent.timeout --value 600000

"Cannot find module 'agentic-qe'"

# Cause: Package not installed correctly
# Solution:
npm install -g agentic-qe
# or
npx agentic-qe <command>

"Permission denied: .agentic-qe/config.json"

# Cause: File permissions issue
# Solution:
chmod 644 .agentic-qe/config.json

Diagnostic Commands

System Diagnostics

# Complete system check
aqe diagnostics

# Check specific components
aqe diagnostics --component fleet
aqe diagnostics --component agents
aqe diagnostics --component memory
aqe diagnostics --component database

Fleet Diagnostics

# Fleet health check
aqe fleet health

# Detailed fleet status
aqe fleet status --verbose --export status.json

# Agent performance metrics
aqe fleet metrics --agents

Log Analysis

# View recent logs
aqe logs --tail 100

# Follow logs in real-time
aqe logs --follow

# Filter logs by level
aqe logs --level error

# Export logs
aqe logs --export logs-$(date +%Y%m%d).log

Getting Help

Self-Service Resources

1. Documentation: https://github.com/proffesor-for-testing/agentic-qe#readme
2. FAQ: Check USER-GUIDE.md FAQ section
3. Examples: Browse /examples directory
4. API Docs: API.md

Community Support

1. GitHub Discussions: https://github.com/proffesor-for-testing/agentic-qe/discussions
2. GitHub Issues: https://github.com/proffesor-for-testing/agentic-qe/issues

Reporting Bugs

When reporting bugs, include:

1. System Information:

aqe diagnostics --export diagnostics.json

2. Reproduction Steps:

aqe test src/service.ts --verbose > output.log 2>&1

3. Configuration:

aqe config show > config.txt

4. Logs:

aqe logs --tail 200 > logs.txt

Bug Report Template

**System Information:**
- OS: Ubuntu 22.04
- Node.js: v18.17.0
- AQE Version: 1.0.1

**Steps to Reproduce:**
1. Run `aqe init`
2. Run `aqe test src/service.ts`
3. Error occurs

**Expected Behavior:**
Tests should be generated

**Actual Behavior:**
Error: Agent failed to start

**Logs:**
[Attach logs.txt]

**Configuration:**
[Attach config.txt]

Preventive Maintenance

Regular Health Checks

# Weekly health check
aqe diagnostics --full

# Monthly fleet optimization
aqe fleet optimize

# Quarterly database cleanup
aqe memory cleanup --aggressive

Best Practices

1. Keep AQE Updated:

npm update -g agentic-qe

2. Monitor Resource Usage:

aqe fleet monitor --export metrics.json

3. Regular Backups:

aqe memory backup --export backup-$(date +%Y%m%d).json

4. Log Rotation:

# Logs automatically rotate at 10MB
# Keep last 5 log files

5. Configuration Validation:

aqe config validate

Advanced Troubleshooting

Debug Mode

# Enable debug logging
LOG_LEVEL=debug aqe execute --verbose

# Enable verbose output
aqe test src/service.ts --verbose --debug

Memory Profiling

# Track memory usage
TRACK_MEMORY=true aqe execute

# Generate heap snapshot
node --expose-gc --heap-prof $(which aqe) execute

Performance Profiling

# Profile test execution
aqe execute --profile

# Benchmark fleet performance
aqe fleet benchmark --iterations 100

Related Documentation

• User Guide - Getting started and basic workflows
• Configuration Guide - Complete configuration reference
• API Reference - Programmatic API documentation
• MCP Integration - Claude Code integration guide