AI Agent Troubleshooting Guides
Step-by-step playbooks for every category of agent error. Each guide covers root causes, fix patterns, and checklists for production deployments.
Token Saving
Reduce token waste, optimize context usage, cut costs without degrading output quality
OpenClaw Errors
Gateway failures, skill errors, session issues, channel connectivity problems
Rate Limit Errors
429 errors, exponential backoff, queue-based throttling, model fallback strategies
Auth Errors
401/403 failures, OAuth refresh, JWT validation, credential caching, auth loops
Context Window Errors
Overflow handling, summarization, truncation strategies, model context limits
Loop / Stuck Errors
Circuit breakers, retry storms, infinite loops, watchdog patterns, exec storms
Docker / Sandbox Errors
EACCES permission errors, networking, OOM, volume mounts, container isolation
Memory / Session Errors
Session amnesia, file persistence, cross-session handoff, context loss prevention
Tool / MCP Failures
Schema mismatches, timeouts, plugin crashes, function call errors, empty results
Hallucination Prevention
Verification pipelines, grounding, temperature calibration, uncertainty expression
Performance Errors
Latency spikes, cold starts, context bloat, connection pooling, tool parallelization
Concurrency Errors
Race conditions, deadlocks, session isolation, message deduplication, ordering
Config Errors
Missing env vars, YAML syntax, model IDs, base URL format, secrets management
Prompt Engineering
Injection prevention, instruction failures, role confusion, output format control
Quick Reference: Which Guide Do I Need?
| Symptom | Guide |
|---|---|
| Agent returns wrong output / makes things up | Hallucination Prevention |
| Agent loops forever or gets stuck | Loop / Stuck Errors |
| 429 Too Many Requests errors | Rate Limit Errors |
| 401 / 403 errors, auth failures | Auth Errors |
| Tool call fails or returns wrong data | Tool / MCP Failures |
| Agent forgets context after restart | Memory / Session Errors |
| Context too long / overflow errors | Context Window Errors |
| Agent running slow / timing out | Performance Errors |
| Costs too high / too many tokens used | Token Saving |
| Agent not following instructions | Prompt Engineering |
| Docker / container crashes | Docker / Sandbox Errors |
| Race conditions, duplicate messages | Concurrency Errors |
| Agent won’t start / config broken | Config Errors |
| OpenClaw gateway errors | OpenClaw Errors |