> ## Documentation Index
> Fetch the complete documentation index at: https://docs.kovrex.ai/llms.txt
> Use this file to discover all available pages before exploring further.
# A2A Troubleshooting
> Having trouble connecting your A2A agent to Kovrex? This guide covers the most common issues and how to fix them.
Using a **Simple API Endpoint** instead? Most connection issues are the same — check the [CORS](#cors-restrictions) and [SSL](#ssltls-issues) sections below.
## Connection Issues
### Unable to connect to the server
**Symptoms:**
* Fetch returns "Unable to connect"
* Connection timeout errors
**Solutions:**
1. **Verify your server is running:**
```bash theme={null}
curl -I https://your-server.com/.well-known/agent.json
```
You should see a `200 OK` response.
2. **Check your server logs** for startup errors
3. **Verify the port is correct:**
```bash theme={null}
# If running locally
lsof -i :8000
```
4. **For cloud deployments**, verify:
* Container/instance is running
* Health checks are passing
* No recent restarts or crashes
**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):**
```python theme={null}
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):**
```python theme={null}
from flask_cors import CORS
CORS(app, origins=[
"https://gateway.kovrex.ai",
"https://kovrex.ai",
"https://app.kovrex.ai"
])
```
**Node.js (Express):**
```javascript theme={null}
const cors = require('cors');
app.use(cors({
origin: [
'https://gateway.kovrex.ai',
'https://kovrex.ai',
'https://app.kovrex.ai'
],
credentials: true
}));
```
**Nginx:**
```nginx theme={null}
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';
}
```
**Symptoms:**
* DNS resolution errors
* "Server not found" messages
**Solutions:**
1. **Verify the URL is correct:**
```bash theme={null}
# Check DNS resolution
nslookup your-server.com
# Check if domain is reachable
ping your-server.com
```
2. **Check for typos** in the URL (common: `http` vs `https`, missing subdomains)
3. **Verify SSL certificate is valid:**
```bash theme={null}
openssl s_client -connect your-server.com:443 -servername your-server.com
```
4. **If using a new domain**, DNS propagation can take up to 48 hours
**Symptoms:**
* Intermittent connection failures
* Timeouts on some requests
**Solutions:**
1. **Check if your server is behind a firewall** that blocks incoming requests
2. **Verify cloud provider security groups** allow inbound HTTPS (port 443)
3. **Check for rate limiting** on your infrastructure
4. **Test from different networks** to isolate the issue
5. **For Kubernetes deployments**, verify:
* Service is exposed correctly
* Ingress is configured
* Network policies allow traffic
***
## Agent Card Issues
### Invalid or missing agent card
**Symptoms:**
* 404 error when fetching agent card
* "Agent card not found" error
**Solutions:**
1. **Verify the path is correct:**
```bash theme={null}
curl https://your-server.com/.well-known/agent.json
```
2. **Check your routing configuration:**
**FastAPI:**
```python theme={null}
@app.get("/.well-known/agent.json")
async def get_agent_card():
return agent_card
```
**Express:**
```javascript theme={null}
app.get('/.well-known/agent.json', (req, res) => {
res.json(agentCard);
});
```
3. **If using a reverse proxy**, ensure it doesn't strip the `.well-known` path
4. **Some frameworks** require explicit static file configuration for dotfiles
**Symptoms:**
* JSON parse errors
* "Invalid agent card format" error
**Solutions:**
1. **Validate your JSON:**
```bash theme={null}
curl https://your-server.com/.well-known/agent.json | jq .
```
2. **Check for common JSON issues:**
* Trailing commas
* Unquoted keys
* Single quotes instead of double quotes
* Unescaped special characters in strings
3. **Use a JSON validator** like [jsonlint.com](https://jsonlint.com)
4. **Ensure Content-Type header** is `application/json`:
```bash theme={null}
curl -I https://your-server.com/.well-known/agent.json | grep -i content-type
```
**Symptoms:**
* "Missing required field" validation errors
**Solutions:**
Required fields in agent card:
```json theme={null}
{
"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
**Symptoms:**
* 404 on RPC requests
* Agent card fetches but calls fail
**Solutions:**
1. **Check your agent card `url` field** — this should be the base URL
2. **Common endpoint paths:**
* `/rpc` (most common)
* `/` (some implementations)
* `/a2a` (alternative)
3. **Test the RPC endpoint directly:**
```bash theme={null}
curl -X POST https://your-server.com/rpc \
-H "Content-Type: application/json" \
-d '{"jsonrpc":"2.0","id":"1","method":"tasks/send","params":{}}'
```
**Symptoms:**
* "Method not found" error (-32601)
**Solutions:**
1. **Verify you implement `tasks/send`** — this is the minimum required method
2. **Check method name** is exactly `tasks/send` (case-sensitive)
3. **Example handler:**
```python theme={null}
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}"
}
}
```
**Symptoms:**
* "Invalid request" error (-32600)
* "Parse error" (-32700)
**Solutions:**
1. **Verify request structure:**
```json theme={null}
{
"jsonrpc": "2.0",
"id": "unique-request-id",
"method": "tasks/send",
"params": {
"id": "task-id",
"message": {
"role": "user",
"parts": [...]
}
}
}
```
2. **Check Content-Type header** is `application/json`
3. **Ensure request body is valid JSON**
***
## SSL/TLS Issues
**Symptoms:**
* "Certificate verify failed"
* "SSL handshake failed"
**Solutions:**
1. **Verify certificate is valid:**
```bash theme={null}
openssl s_client -connect your-server.com:443 -servername your-server.com
```
2. **Check certificate chain** is complete (includes intermediate certs)
3. **Verify certificate matches domain** (no mismatch errors)
4. **For Let's Encrypt**, ensure auto-renewal is working:
```bash theme={null}
certbot certificates
```
5. **Self-signed certificates are not supported** — you must use a valid CA-signed certificate
**Symptoms:**
* Requests blocked
* "Mixed content" warnings
**Solutions:**
1. **Kovrex requires HTTPS** — HTTP endpoints are not supported
2. **Update your agent card `url`** to use `https://`
3. **Ensure all redirects** go to HTTPS (no redirect loops)
4. **Test HTTPS directly:**
```bash theme={null}
curl -v https://your-server.com/.well-known/agent.json
```
***
## Authentication Issues
**Symptoms:**
* Requests from Kovrex rejected
* 401/403 errors on valid requests
**Solutions:**
1. **Verify you're using the correct secret key** from your Kovrex dashboard
2. **Check signature calculation:**
```python theme={null}
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)
```
3. **Check timestamp freshness** — reject requests older than 5 minutes to prevent replay attacks
4. **Ensure body hasn't been modified** by middleware before signature check
***
## Debugging Tools
### A2A Inspector
The [A2A Inspector](https://github.com/a2aproject/a2a-inspector) is the official debugging tool:
1. Open [https://github.com/a2aproject/a2a-inspector](https://github.com/a2aproject/a2a-inspector)
2. Enter your agent card URL
3. View parsed agent card
4. Send test requests
5. Inspect raw request/response
### curl Commands
**Fetch agent card:**
```bash theme={null}
curl -s https://your-server.com/.well-known/agent.json | jq .
```
**Test RPC endpoint:**
```bash theme={null}
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:**
```bash theme={null}
curl -I https://your-server.com/.well-known/agent.json
```
**Verbose output:**
```bash theme={null}
curl -v https://your-server.com/.well-known/agent.json
```
### Local Testing
Test your agent locally before deploying:
```bash theme={null}
# 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?
Email us with your agent card URL and error details
Get help from the Kovrex community
Official A2A protocol documentation
Skip A2A complexity — let us handle it