AEA Protocol - Troubleshooting Guide

Version: 0.1.0 Last Updated: 2025-10-25

Complete guide to diagnosing and fixing common AEA Protocol issues.

📋 Table of Contents

Quick Diagnostics
Installation Issues
Message Not Appearing
Processing Failures
Hook Problems
Registry Issues
Monitor Problems
GitHub Integration Issues
Performance Issues
Error Reference

Quick Diagnostics

Run these commands to quickly diagnose your AEA setup:

# Check if AEA is installed
ls -la .aea/

# Verify required tools
which jq bash
jq --version

# Test message check
bash .aea/scripts/aea-check.sh

# Check registry
bash .aea/scripts/aea-registry.sh list

# View recent logs
tail -20 .aea/agent.log

# Check monitor status
bash .aea/scripts/aea-monitor.sh status

Installation Issues

❌ "No such file or directory: .aea"

Problem: AEA not installed in current directory.

Solution:

# Install AEA in current directory
bash /path/to/aea/scripts/install-aea.sh

# Or one-line install
curl -fsSL https://raw.githubusercontent.com/openSVM/aea/main/install.sh | bash

❌ "jq: command not found"

Problem: jq not installed.

Solution:

# Debian/Ubuntu
sudo apt-get update && sudo apt-get install -y jq

# macOS
brew install jq

# RedHat/CentOS
sudo yum install jq

# Alpine
apk add jq

❌ Permission denied when running scripts

Problem: Scripts not executable.

Solution:

chmod +x .aea/scripts/*.sh

❌ "Failed to create required directories"

Problem: No write permission in directory.

Solution:

# Check permissions
ls -la | grep .aea

# Fix ownership
sudo chown -R $USER:$USER .aea/

# Or run with appropriate permissions
sudo bash .aea/scripts/aea-check.sh

Message Not Appearing

❌ Sent message not showing up

Checklist:

Verify message was created:

# In recipient repo
ls -la .aea/message-*.json

Check if already processed:
```
ls -la .aea/.processed/
```

Validate message format:

# Check JSON is valid
jq empty .aea/message-*.json

# Validate required fields
bash .aea/scripts/aea-validate-message.sh .aea/message-*.json

Check agent registry:

# Verify recipient is registered
bash .aea/scripts/aea-registry.sh list

Verify hooks are running:

cat .claude/settings.json
# Should contain AEA hooks

❌ Messages not auto-checking

Problem: Hooks not configured or disabled.

Solution:

# Check hooks configuration
cat .claude/settings.json

# Reinstall hooks
bash .aea/scripts/install-aea.sh --hooks-only

# Or manually add to .claude/settings.json:
{
  "hooks": {
    "SessionStart": {
      "command": "bash .aea/scripts/aea-auto-processor.sh",
      "description": "Auto-process AEA messages on session start",
      "enabled": true
    },
    "UserPromptSubmit": "bash .aea/scripts/aea-check.sh",
    "Stop": {
      "command": "bash .aea/scripts/aea-auto-processor.sh",
      "description": "Auto-process AEA messages after task completion",
      "enabled": true
    }
  }
}

Processing Failures

❌ "No unprocessed messages" but messages exist

Problem: Messages already marked as processed.

Diagnosis:

# List unprocessed messages
for msg in .aea/message-*.json; do
  basename=$(basename "$msg")
  if [ ! -f ".aea/.processed/$basename" ]; then
    echo "Unprocessed: $basename"
  fi
done

Solution:

# Clear processed markers to reprocess
rm .aea/.processed/message-*.json

# Or remove specific message marker
rm .aea/.processed/message-20251025T120000000Z-from-agent.json

❌ Message validation fails

Problem: Message doesn't conform to protocol v0.1.0.

Common Issues:

Wrong protocol version:

❌ "protocol_version": "1.0"
✅ "protocol_version": "0.1.0"

Wrong field names:

❌ "from": {...}
✅ "sender": {...}

❌ "to": {...}
✅ "recipient": {...}

❌ "priority": "high"
✅ "routing": {"priority": "high"}

❌ "message": {"subject": "..."}
✅ "content": {"subject": "..."}

Missing required fields:

# Run validator to see what's missing
bash .aea/scripts/aea-validate-message.sh .aea/message-*.json

Solution: Update message to v0.1.0 schema (see PROTOCOL.md)

❌ "Failed to parse JSON"

Problem: Invalid JSON syntax.

Diagnosis:

# Check JSON syntax
jq empty .aea/message-*.json

Common Issues:

Missing commas
Trailing commas (not allowed in JSON)
Unescaped quotes in strings
Missing closing brackets

Solution:

# Use jq to pretty-print and fix formatting
cat .aea/message-bad.json | jq '.' > .aea/message-fixed.json

Hook Problems

❌ Hooks not triggering

Problem: Claude Code not executing AEA hooks.

Diagnosis:

# Check if hooks file exists
cat .claude/settings.json

# Check logs for hook execution
tail -f .aea/agent.log

Solutions:

Restart Claude Code session

Verify hook syntax:

{
  "hooks": {
    "UserPromptSubmit": "bash .aea/scripts/aea-check.sh"
  }
}

Check script paths are correct (relative to project root)
Ensure scripts are executable: chmod +x .aea/scripts/*.sh

❌ Hook errors in Claude Code

Problem: Hook command fails.

Diagnosis:

# Manually run hook command to see error
bash .aea/scripts/aea-check.sh

# Check for script errors
bash -x .aea/scripts/aea-check.sh

Solution: Fix script errors, ensure dependencies (jq) are installed.

Registry Issues

❌ "Agent not found in registry"

Problem: Destination agent not registered.

Solution:

# Register the agent
bash .aea/scripts/aea-registry.sh register agent-name /path/to/repo "Description"

# Verify registration
bash .aea/scripts/aea-registry.sh list

❌ "Registry file not found"

Problem: Agent registry not initialized.

Solution:

# Initialize registry
mkdir -p ~/.config/aea
cat > ~/.config/aea/agents.yaml << 'EOF'
agents: {}
EOF

# Or let AEA create it
bash .aea/scripts/aea-registry.sh list

❌ Registry corruption

Problem: Invalid YAML in registry file.

Diagnosis:

cat ~/.config/aea/agents.yaml

Solution:

# Backup corrupted registry
cp ~/.config/aea/agents.yaml ~/.config/aea/agents.yaml.bak

# Recreate registry
cat > ~/.config/aea/agents.yaml << 'EOF'
agents:
  agent-1:
    path: /path/to/repo1
    enabled: true
    description: "Description"
EOF

# Re-register all agents
bash .aea/scripts/aea-registry.sh register agent-name /path "Description"

Monitor Problems

❌ Monitor won't start

Problem: Monitor script fails to start.

Diagnosis:

# Check monitor status
bash .aea/scripts/aea-monitor.sh status

# Check logs
cat .aea/monitor.log

# Try manual start
bash .aea/scripts/aea-monitor.sh start

Common Issues:

Already running:

bash .aea/scripts/aea-monitor.sh stop
bash .aea/scripts/aea-monitor.sh start

No write permission:
```
chmod +w .aea/
```
Script not executable:
```
chmod +x .aea/scripts/aea-monitor.sh
```

❌ Monitor stops unexpectedly

Problem: Background process dies.

Diagnosis:

# Check monitor log
tail -50 .aea/monitor.log

# Check system logs
journalctl -u aea-monitor  # If using systemd

Solutions:

Increase check interval (reduce CPU usage):

# In agent-config.yaml
monitoring:
  check_interval_seconds: 300  # 5 minutes instead of 60

Check for disk space:
```
df -h
```

Restart monitor:

bash .aea/scripts/aea-monitor.sh restart

GitHub Integration Issues

❌ GitHub issues not appearing

Problem: GitHub integration not configured.

Solution:

# Add to .aea/agent-config.yaml:
github_integration:
  enabled: true
  repository: "owner/repo"
  labels:
    - bug
    - enhancement
  check_interval_minutes: 60

❌ "API rate limit exceeded"

Problem: Too many GitHub API requests.

Solutions:

Increase check interval:

github_integration:
  check_interval_minutes: 120  # Check every 2 hours

Use GitHub token for higher limits:

github_integration:
  token: "ghp_your_token_here"  # Optional, increases rate limit

Filter by labels to reduce requests:

github_integration:
  labels:
    - critical
    - blocking

Performance Issues

❌ Slow message checking

Problem: Check takes too long.

Diagnosis:

time bash .aea/scripts/aea-check.sh

Solutions:

Clean up old messages:

# Move old processed messages
mkdir -p .aea/archive
mv .aea/message-2025-01-*.json .aea/archive/

Reduce GitHub check frequency:

github_integration:
  check_interval_minutes: 120

Optimize jq queries (for developers)

❌ High CPU usage from monitor

Problem: Monitor using too much CPU.

Solution:

# In agent-config.yaml
monitoring:
  check_interval_seconds: 300  # Check every 5 minutes

Error Reference

Common Error Messages

Error	Cause	Solution
`jq: command not found`	jq not installed	Install jq: `apt-get install jq` or `brew install jq`
`No such file or directory: .aea`	AEA not installed	Run installation script
`Invalid JSON`	Malformed message	Validate with `jq empty file.json`
`Missing required field: .message_id`	Incomplete message	Add all required fields per PROTOCOL.md
`Agent not found in registry`	Agent not registered	Register with `aea-registry.sh register`
`Permission denied`	No execute permission	Run `chmod +x .aea/scripts/*.sh`
`Failed to create required directories`	No write permission	Fix permissions or run as appropriate user
`Protocol version mismatch`	Wrong version	Use `"protocol_version": "0.1.0"`

Script Exit Codes

Exit Code	Meaning
0	Success
1	General error
2	Missing dependency
3	Invalid configuration
4	File not found
5	Permission denied

Getting Help

If you can't resolve your issue:

Check logs:

cat .aea/agent.log
tail -50 .aea/monitor.log

Run diagnostics:

bash .aea/scripts/aea-check.sh
bash .aea/scripts/aea-validate-message.sh .aea/message-*.json

Create GitHub issue: https://github.com/openSVM/aea/issues
- Include error messages
- Include relevant logs
- Include system info: uname -a, jq --version, bash --version
Check documentation:

Debug Mode

Enable verbose logging for troubleshooting:

# Run scripts with debug output
bash -x .aea/scripts/aea-check.sh

# Enable detailed logging in agent-config.yaml
logging:
  level: debug
  file: .aea/debug.log

💬 Still Need Help?

If you can't resolve your issue:

🐛 Report a Bug

Report Bug - Use our bug report template

❓ Ask a Question

Ask Question - Get help from the community

💭 Discuss

Start Discussion - General questions and ideas

📖 More Resources

FAQ - Frequently asked questions
Examples - Real-world usage scenarios
Agent Guide - Agent behavior guidelines

When reporting issues, please include:

Error messages from logs (.aea/agent.log)
Your environment (OS, bash version, jq version)
Relevant configuration (.aea/agent-config.yaml)
Steps to reproduce the problem

FilesExpand file tree

TROUBLESHOOTING.md

Latest commit

History

TROUBLESHOOTING.md

File metadata and controls

AEA Protocol - Troubleshooting Guide

📋 Table of Contents

Quick Diagnostics

Installation Issues

❌ "No such file or directory: .aea"

❌ "jq: command not found"

❌ Permission denied when running scripts

❌ "Failed to create required directories"

Message Not Appearing

❌ Sent message not showing up

❌ Messages not auto-checking

Processing Failures

❌ "No unprocessed messages" but messages exist

❌ Message validation fails

❌ "Failed to parse JSON"

Hook Problems

❌ Hooks not triggering

❌ Hook errors in Claude Code

Registry Issues

❌ "Agent not found in registry"

❌ "Registry file not found"

❌ Registry corruption

Monitor Problems

❌ Monitor won't start

❌ Monitor stops unexpectedly

GitHub Integration Issues

❌ GitHub issues not appearing

❌ "API rate limit exceeded"

Performance Issues

❌ Slow message checking

❌ High CPU usage from monitor

Error Reference

Common Error Messages

Script Exit Codes

Getting Help

Debug Mode

💬 Still Need Help?

🐛 Report a Bug

❓ Ask a Question

💭 Discuss

📖 More Resources