Troubleshooting

Common errors, debugging patterns, and solutions for AgentField.

Diagnose and fix common issues when building with AgentField.

Common Errors

Error	Cause	Fix
ConnectionRefusedError	Control plane is not running	Start with af server or check host/port
401 Unauthorized	Missing or invalid API key	Set AGENTFIELD_API_KEY or pass api_key= to Agent
404 Agent not found	Agent is not registered	Ensure agent is running with app.serve()
429 Too Many Requests	LLM provider rate limit	Add retry logic or configure fallback models
TimeoutError	Execution exceeded deadline	Increase timeout or switch to async execution

---

Debugging Reasoners

LLM Errors

Memory Errors

Network and Connectivity

Environment Variables Reference