Common Issues and Troubleshooting¶

This guide covers the most common issues encountered when using A2A Registry and their solutions.

Installation Issues¶

Issue: `pip install a2a-registry` fails¶

Symptoms:

ERROR: Could not find a version that satisfies the requirement a2a-registry

Solutions:

Check Python version:
```
python --version  # Should be 3.9+
```
Upgrade pip:
```
pip install --upgrade pip
```

Install from source:

git clone https://github.com/allenday/a2a-registry.git
cd a2a-registry
pip install -e .

Issue: Import errors after installation¶

Symptoms:

ImportError: No module named 'a2a_registry'

Solutions:

Verify installation:
```
pip list | grep a2a-registry
```
Check virtual environment:
```
which python
which pip
```

Reinstall in clean environment:

python -m venv fresh_env
source fresh_env/bin/activate  # On Windows: fresh_env\Scripts\activate
pip install a2a-registry

Server Startup Issues¶

Issue: Server won't start¶

Symptoms:

Error: Could not start server on port 8000

Common Causes & Solutions:

Port already in use:

# Check what's using port 8000
lsof -i :8000  # On macOS/Linux
netstat -ano | findstr :8000  # On Windows

# Use different port
a2a-registry serve --port 8001

Permission denied:

# Use unprivileged port (>1024)
a2a-registry serve --port 8080

# Or run with sudo (not recommended)
sudo a2a-registry serve --port 80

Missing dependencies:
```
pip install fastapi uvicorn
```

Issue: Server starts but can't connect¶

Symptoms:

Connection refused when accessing http://localhost:8000

Solutions:

Check bind address:

# Server only listening on localhost
a2a-registry serve --host 0.0.0.0  # Listen on all interfaces

Verify server is running:
```
curl http://localhost:8000/health
```

Check firewall settings:

# On Linux
sudo ufw status
sudo ufw allow 8000

# On macOS
# Check System Preferences > Security & Privacy > Firewall

Registration Issues¶

Issue: Agent registration fails¶

Symptoms:

{
  "error": "Validation error",
  "details": "Invalid agent card format"
}

Common Validation Errors:

Missing required fields:

# ❌ Incomplete agent card
agent_card = {
    "name": "my-agent"
    # Missing required fields
}

# ✅ Complete agent card
agent_card = {
    "name": "my-agent",
    "description": "My test agent",
    "url": "http://localhost:3000",
    "version": "0.420.0",
    "protocol_version": "0.3.0",
    "capabilities": {
        "streaming": False,
        "push_notifications": False,
        "state_transition_history": False
    },
    "default_input_modes": ["text"],
    "default_output_modes": ["text"],
    "skills": [],
    "preferred_transport": "http"
}

Invalid URL format:

# ❌ Invalid URLs
"url": "localhost:3000"        # Missing protocol
"url": "http:/localhost:3000"  # Typo in protocol

# ✅ Valid URLs
"url": "http://localhost:3000"
"url": "https://api.example.com"
"url": "grpc://service.example.com:50051"

Invalid skill format:

# ❌ Invalid skill format
"skills": ["skill1", "skill2"]  # Should be objects

# ✅ Valid skill format
"skills": [
    {"id": "skill1", "description": "First skill"},
    {"id": "skill2", "description": "Second skill"}
]

Issue: Duplicate agent registration¶

Symptoms:

{
  "error": "Agent already exists",
  "agent_id": "existing-agent"
}

Solutions:

Check existing registrations:
```
curl http://localhost:8000/agents
```

Unregister old agent:

curl -X DELETE http://localhost:8000/agents/my-agent

Use unique agent names:

import uuid

agent_card = {
    "name": f"my-agent-{uuid.uuid4().hex[:8]}",
    # ... rest of card
}

Discovery Issues¶

Issue: Can't find registered agents¶

Symptoms: - Agents register successfully but don't appear in search results - Empty responses from list/search endpoints

Solutions:

Verify agent is registered:

# List all agents
curl http://localhost:8000/agents

# Get specific agent
curl http://localhost:8000/agents/my-agent-id

Check search criteria:

# ❌ Too restrictive search
agents = await client.search_agents(
    skills=["exact_skill_name"],
    query="very specific query"
)

# ✅ Broader search
agents = await client.search_agents(query="general")

Case sensitivity issues:

# Search is case-insensitive for descriptions but case-sensitive for skill IDs

# ❌ Wrong case for skill ID
agents = await client.search_agents(skills=["Translate"])

# ✅ Correct case
agents = await client.search_agents(skills=["translate"])

Issue: Search returns unexpected results¶

Solutions:

Understand search behavior:
Query searches in name and description (case-insensitive)
Skills must match exactly (case-sensitive)
Multiple criteria are AND-ed together

Debug search criteria:

# Test each criterion separately
by_query = await client.search_agents(query="weather")
by_skills = await client.search_agents(skills=["forecast"])
combined = await client.search_agents(query="weather", skills=["forecast"])

print(f"By query: {len(by_query)}")
print(f"By skills: {len(by_skills)}")
print(f"Combined: {len(combined)}")

Network and Connectivity Issues¶

Issue: Connection timeouts¶

Symptoms:

TimeoutError: Request timed out after 30 seconds

Solutions:

Increase timeout:

client = A2ARegistryClient(
    "http://localhost:8000",
    timeout=60.0  # Increase to 60 seconds
)

Check network connectivity:
```
ping localhost
telnet localhost 8000
```

Use retry logic:

import asyncio

async def register_with_retry(client, agent_card, max_retries=3):
    for attempt in range(max_retries):
        try:
            return await client.register_agent(agent_card)
        except TimeoutError:
            if attempt == max_retries - 1:
                raise
            await asyncio.sleep(2 ** attempt)  # Exponential backoff

Issue: DNS resolution problems¶

Symptoms:

DNSError: Could not resolve hostname

Solutions:

Use IP addresses:

# Instead of hostname
client = A2ARegistryClient("http://127.0.0.1:8000")

Check DNS configuration:
```
nslookup localhost
dig localhost
```

Add to hosts file (if using custom hostnames):

# /etc/hosts (Linux/macOS) or C:\Windows\System32\drivers\etc\hosts (Windows)
127.0.0.1 my-registry.local

Performance Issues¶

Issue: Slow response times¶

Symptoms: - Registration takes several seconds - Search requests are slow - High memory usage

Solutions:

Monitor server resources:

# Check CPU and memory usage
top
htop

# Check specific process
ps aux | grep a2a-registry

Optimize agent card size:

# ❌ Excessive data
agent_card = {
    "description": "Very long description..." * 1000,
    "skills": [{"id": f"skill{i}", "description": "..."} for i in range(1000)]
}

# ✅ Reasonable size
agent_card = {
    "description": "Concise description",
    "skills": [
        {"id": "main_skill", "description": "Primary functionality"}
    ]
}

Limit search results:

# Future: Add pagination
# For now, use specific search criteria
agents = await client.search_agents(
    query="specific term",
    skills=["exact_skill"]
)

Issue: Memory leaks¶

Symptoms: - Server memory usage keeps growing - Eventually crashes with OutOfMemory

Solutions:

Restart server periodically:

# Simple cron job (production should use proper process management)
0 2 * * * pkill -f a2a-registry && sleep 5 && a2a-registry serve &

Monitor registrations:

# Check registry size
response = await client.health_check()
print(f"Registered agents: {response.get('agents_count', 'unknown')}")

Clean up old agents:

# Periodic cleanup of inactive agents
async def cleanup_inactive_agents():
    agents = await client.list_agents()
    for agent in agents:
        if not await ping_agent(agent['url']):
            await client.unregister_agent(agent['name'])

Development and Testing Issues¶

Issue: Tests fail with "connection refused"¶

Solutions:

Start test registry:

import pytest
import asyncio
from a2a_registry.server import create_app

@pytest.fixture
async def test_registry():
    app = create_app()
    # Start test server on different port
    # Use TestClient for testing

Use test client:

from fastapi.testclient import TestClient
from a2a_registry.server import create_app

app = create_app()
client = TestClient(app)

# Test without running actual server
response = client.post("/agents", json={"agent_card": {...}})
assert response.status_code == 201

Issue: Import errors in development¶

Solutions:

Install in development mode:
```
pip install -e .
```

Add to Python path:

import sys
import os
sys.path.insert(0, os.path.join(os.path.dirname(__file__), '..'))

from a2a_registry import A2ARegistryClient

Configuration Issues¶

Issue: Environment variables not loaded¶

Solutions:

Check environment variable names:

export A2A_REGISTRY_URL=http://localhost:8000
export A2A_REGISTRY_TIMEOUT=30

Use .env file:

# .env
A2A_REGISTRY_URL=http://localhost:8000
A2A_REGISTRY_TIMEOUT=30

Verify loading:

import os
print(f"Registry URL: {os.getenv('A2A_REGISTRY_URL')}")

Logging and Debugging¶

Enable Debug Logging¶

import logging

# Enable debug logging
logging.basicConfig(level=logging.DEBUG)

# Or for specific logger
logger = logging.getLogger("a2a_registry")
logger.setLevel(logging.DEBUG)

Server Debug Mode¶

# Start server with debug logging
a2a-registry serve --log-level DEBUG

# Or with reload for development
a2a-registry serve --reload --log-level DEBUG

Client Debug Information¶

import aiohttp
import logging

# Enable aiohttp debug logging
logging.getLogger("aiohttp").setLevel(logging.DEBUG)

# Custom debug wrapper
class DebugRegistryClient(A2ARegistryClient):
    async def _make_request(self, method, url, **kwargs):
        print(f"Making {method} request to {url}")
        print(f"Data: {kwargs.get('json')}")

        response = await super()._make_request(method, url, **kwargs)

        print(f"Response status: {response.status}")
        print(f"Response data: {await response.text()}")

        return response

Getting Help¶

Check Server Health¶

curl http://localhost:8000/health

Expected response:

{
  "status": "healthy",
  "version": "0.1.0",
  "agents_count": 5
}

Collect Debug Information¶

# System info
python --version
pip list | grep -E "(a2a|fastapi|uvicorn)"

# Network info
netstat -an | grep 8000
curl -v http://localhost:8000/health

# Logs
journalctl -u a2a-registry  # If running as service

Community Support¶

GitHub Issues - Bug reports and feature requests
GitHub Discussions - Questions and community support
Documentation - Complete documentation

Reporting Bugs¶

When reporting issues, please include:

Environment information:
Python version
Operating system
Package versions
Steps to reproduce:
Minimal code example
Configuration used
Expected vs actual behavior
Logs and error messages:
Full error tracebacks
Server logs
Network request/response details

Example bug report template:

**Environment:**
- Python: 3.9.7
- OS: Ubuntu 20.04
- a2a-registry: 0.1.5

**Issue:**
Agent registration fails with validation error

**Steps to reproduce:**
1. Start registry: `a2a-registry serve`
2. Register agent with code:
   ```python
   # Code here
   ```
3. See error: `Validation error: ...`

**Expected behavior:**
Agent should register successfully

**Actual behavior:**
Gets validation error

**Logs:**

Full error traceback here

Next Steps¶

Review Performance Tuning for optimization tips
Check Logging and Monitoring for observability setup
Explore Developer Guide for contribution guidelines

Common Issues and Troubleshooting¶

Installation Issues¶

Issue: pip install a2a-registry fails¶

Issue: Import errors after installation¶

Server Startup Issues¶

Issue: Server won't start¶

Issue: Server starts but can't connect¶

Registration Issues¶

Issue: Agent registration fails¶

Issue: Duplicate agent registration¶

Discovery Issues¶

Issue: Can't find registered agents¶

Issue: Search returns unexpected results¶

Network and Connectivity Issues¶

Issue: Connection timeouts¶

Issue: DNS resolution problems¶

Performance Issues¶

Issue: Slow response times¶

Issue: Memory leaks¶

Development and Testing Issues¶

Issue: Tests fail with "connection refused"¶

Issue: Import errors in development¶

Configuration Issues¶

Issue: Environment variables not loaded¶

Logging and Debugging¶

Enable Debug Logging¶

Server Debug Mode¶

Client Debug Information¶

Getting Help¶

Check Server Health¶

Collect Debug Information¶

Community Support¶

Reporting Bugs¶

Next Steps¶

Issue: `pip install a2a-registry` fails¶