A2A Troubleshooting

Using a Simple API Endpoint instead? Most connection issues are the same — check the CORS and SSL sections below.

Connection Issues

Unable to connect to the server

Your A2A agent server is not running

Symptoms:

Fetch returns “Unable to connect”
Connection timeout errors

Solutions:

Verify your server is running:

curl -I https://your-server.com/.well-known/agent.json

You should see a 200 OK response.

Check your server logs for startup errors
Verify the port is correct:

# If running locally
lsof -i :8000

For cloud deployments, verify:
- Container/instance is running
- Health checks are passing
- No recent restarts or crashes

CORS restrictions

Symptoms:

Browser console shows CORS errors
Fetch works from curl but fails in Kovrex portal

Solutions:Your server must allow requests from gateway.kovrex.ai. Add these CORS headers:Python (FastAPI):

from fastapi.middleware.cors import CORSMiddleware

app.add_middleware(
    CORSMiddleware,
    allow_origins=[
        "https://gateway.kovrex.ai",
        "https://kovrex.ai",
        "https://app.kovrex.ai"
    ],
    allow_credentials=True,
    allow_methods=["*"],
    allow_headers=["*"],
)

Python (Flask):

from flask_cors import CORS

CORS(app, origins=[
    "https://gateway.kovrex.ai",
    "https://kovrex.ai",
    "https://app.kovrex.ai"
])

Node.js (Express):

const cors = require('cors');

app.use(cors({
  origin: [
    'https://gateway.kovrex.ai',
    'https://kovrex.ai',
    'https://app.kovrex.ai'
  ],
  credentials: true
}));

Nginx:

location / {
    if ($request_method = 'OPTIONS') {
        add_header 'Access-Control-Allow-Origin' 'https://gateway.kovrex.ai';
        add_header 'Access-Control-Allow-Methods' 'GET, POST, OPTIONS';
        add_header 'Access-Control-Allow-Headers' 'Content-Type, Authorization';
        return 204;
    }
    
    add_header 'Access-Control-Allow-Origin' 'https://gateway.kovrex.ai';
}

Invalid domain or server is down

Symptoms:

DNS resolution errors
“Server not found” messages

Solutions:

Verify the URL is correct:

# Check DNS resolution
nslookup your-server.com

# Check if domain is reachable
ping your-server.com

Check for typos in the URL (common: http vs https, missing subdomains)
Verify SSL certificate is valid:

openssl s_client -connect your-server.com:443 -servername your-server.com

If using a new domain, DNS propagation can take up to 48 hours

Network connectivity issues

Symptoms:

Intermittent connection failures
Timeouts on some requests

Solutions:

Check if your server is behind a firewall that blocks incoming requests
Verify cloud provider security groups allow inbound HTTPS (port 443)
Check for rate limiting on your infrastructure
Test from different networks to isolate the issue
For Kubernetes deployments, verify:
- Service is exposed correctly
- Ingress is configured
- Network policies allow traffic

Agent Card Issues

Invalid or missing agent card

Agent card not found at /.well-known/agent.json

Symptoms:

404 error when fetching agent card
“Agent card not found” error

Solutions:

Verify the path is correct:

curl https://your-server.com/.well-known/agent.json

Check your routing configuration:

FastAPI:

@app.get("/.well-known/agent.json")
async def get_agent_card():
    return agent_card

Express:

app.get('/.well-known/agent.json', (req, res) => {
  res.json(agentCard);
});

If using a reverse proxy, ensure it doesn’t strip the .well-known path
Some frameworks require explicit static file configuration for dotfiles

Agent card JSON is malformed

Symptoms:

JSON parse errors
“Invalid agent card format” error

Solutions:

Validate your JSON:

curl https://your-server.com/.well-known/agent.json | jq .

Check for common JSON issues:
- Trailing commas
- Unquoted keys
- Single quotes instead of double quotes
- Unescaped special characters in strings
Use a JSON validator like jsonlint.com
Ensure Content-Type header is application/json:

curl -I https://your-server.com/.well-known/agent.json | grep -i content-type

Missing required fields

Symptoms:

“Missing required field” validation errors

Solutions:Required fields in agent card:

{
  "name": "Required - Agent name",
  "description": "Required - What the agent does",
  "url": "Required - Base URL for RPC endpoint",
  "version": "Required - Semantic version",
  "skills": [
    {
      "id": "required_skill_id",
      "name": "Required - Skill name",
      "description": "Required - Skill description",
      "inputSchema": {},
      "outputSchema": {}
    }
  ]
}

Verify all required fields are present and non-empty.

JSON-RPC Issues

RPC endpoint not responding

Wrong RPC endpoint path

Symptoms:

404 on RPC requests
Agent card fetches but calls fail

Solutions:

Check your agent card url field — this should be the base URL
Common endpoint paths:
- /rpc (most common)
- / (some implementations)
- /a2a (alternative)
Test the RPC endpoint directly:

curl -X POST https://your-server.com/rpc \
  -H "Content-Type: application/json" \
  -d '{"jsonrpc":"2.0","id":"1","method":"tasks/send","params":{}}'

Method not supported

Symptoms:

“Method not found” error (-32601)

Solutions:

Verify you implement tasks/send — this is the minimum required method
Check method name is exactly tasks/send (case-sensitive)
Example handler:

async def handle_jsonrpc(request):
    data = await request.json()
    method = data.get("method")
    
    if method == "tasks/send":
        return await handle_task_send(data)
    else:
        return {
            "jsonrpc": "2.0",
            "id": data.get("id"),
            "error": {
                "code": -32601,
                "message": f"Method not found: {method}"
            }
        }

Invalid request format

Symptoms:

“Invalid request” error (-32600)
“Parse error” (-32700)

Solutions:

Verify request structure:

{
  "jsonrpc": "2.0",
  "id": "unique-request-id",
  "method": "tasks/send",
  "params": {
    "id": "task-id",
    "message": {
      "role": "user",
      "parts": [...]
    }
  }
}

Check Content-Type header is application/json
Ensure request body is valid JSON

SSL/TLS Issues

SSL certificate errors

Symptoms:

“Certificate verify failed”
“SSL handshake failed”

Solutions:

Verify certificate is valid:

openssl s_client -connect your-server.com:443 -servername your-server.com

Check certificate chain is complete (includes intermediate certs)
Verify certificate matches domain (no mismatch errors)
For Let’s Encrypt, ensure auto-renewal is working:

certbot certificates

Self-signed certificates are not supported — you must use a valid CA-signed certificate

Mixed content / HTTPS required

Symptoms:

Requests blocked
“Mixed content” warnings

Solutions:

Kovrex requires HTTPS — HTTP endpoints are not supported
Update your agent card url to use https://
Ensure all redirects go to HTTPS (no redirect loops)
Test HTTPS directly:

curl -v https://your-server.com/.well-known/agent.json

Authentication Issues

Signature verification failing

Symptoms:

Requests from Kovrex rejected
401/403 errors on valid requests

Solutions:

Verify you’re using the correct secret key from your Kovrex dashboard
Check signature calculation:

import hmac
import hashlib

def verify_signature(request, secret_key):
    signature = request.headers.get("X-Kovrex-Signature", "")
    timestamp = request.headers.get("X-Kovrex-Timestamp", "")
    body = request.body.decode('utf-8')
    
    # Signature is over: timestamp.body
    message = f"{timestamp}.{body}"
    
    expected = hmac.new(
        secret_key.encode(),
        message.encode(),
        hashlib.sha256
    ).hexdigest()
    
    return hmac.compare_digest(f"sha256={expected}", signature)

Check timestamp freshness — reject requests older than 5 minutes to prevent replay attacks
Ensure body hasn’t been modified by middleware before signature check

Debugging Tools

A2A Inspector

The A2A Inspector is the official debugging tool:

Open https://github.com/a2aproject/a2a-inspector
Enter your agent card URL
View parsed agent card
Send test requests
Inspect raw request/response

curl Commands

Fetch agent card:

curl -s https://your-server.com/.well-known/agent.json | jq .

Test RPC endpoint:

curl -X POST https://your-server.com/rpc \
  -H "Content-Type: application/json" \
  -d '{
    "jsonrpc": "2.0",
    "id": "test-1",
    "method": "tasks/send",
    "params": {
      "id": "task-1",
      "message": {
        "role": "user",
        "parts": [{"type": "text", "text": "Hello"}]
      }
    }
  }' | jq .

Check headers:

curl -I https://your-server.com/.well-known/agent.json

Verbose output:

curl -v https://your-server.com/.well-known/agent.json

Local Testing

Test your agent locally before deploying:

# Run your agent on localhost
python your_agent.py

# In another terminal, use ngrok for public URL
ngrok http 8000

# Use the ngrok URL in Kovrex portal for testing

Common Error Codes

Code	Meaning	Solution
`-32700`	Parse error (invalid JSON)	Check request body is valid JSON
`-32600`	Invalid request	Verify JSON-RPC structure
`-32601`	Method not found	Implement `tasks/send` method
`-32602`	Invalid params	Check params match expected schema
`-32603`	Internal error	Check server logs for details

Still Stuck?

Contact Support

Email us with your agent card URL and error details

Community Discord

Get help from the Kovrex community

A2A Protocol Docs

Official A2A protocol documentation

Simple API Option

Skip A2A complexity — let us handle it

Getting Started

Consumer Guide

Operator Guide

Examples

API Reference

Policies

A2A Troubleshooting

Connection Issues

Unable to connect to the server

Agent Card Issues

Invalid or missing agent card

JSON-RPC Issues

RPC endpoint not responding

SSL/TLS Issues

Authentication Issues

Debugging Tools

A2A Inspector

curl Commands

Local Testing

Common Error Codes

Still Stuck?

Contact Support

Community Discord

A2A Protocol Docs

Simple API Option

Getting Started

Consumer Guide

Operator Guide

Examples

API Reference

Policies

​Connection Issues

​Unable to connect to the server

​Agent Card Issues

​Invalid or missing agent card

​JSON-RPC Issues

​RPC endpoint not responding

​SSL/TLS Issues

​Authentication Issues

​Debugging Tools

​A2A Inspector

​curl Commands

​Local Testing

​Common Error Codes

​Still Stuck?

Contact Support

Community Discord

A2A Protocol Docs

Simple API Option

Connection Issues

Unable to connect to the server

Agent Card Issues

Invalid or missing agent card

JSON-RPC Issues

RPC endpoint not responding

SSL/TLS Issues

Authentication Issues

Debugging Tools

A2A Inspector

curl Commands

Local Testing

Common Error Codes

Still Stuck?