Debugging a Crew That Won't Converge on an Answer
A crew that "won't converge" usually loops on tools, re-delegates forever, or hands off mush between agents until max_iter or your wallet stops it.
Use this cheatsheet to find whether the bug is task design, role overlap, tools, process, or missing stop rails.
How to Use This Cheatsheet
- Reproduce once with
verbose=Trueand saved logs (output_log_file). - Walk A → F in order; most failures die in A-C.
- Change one variable per run (expected_output, tools, process, model).
- Capture
tasks_outputand token usage after every experiment.
A - Capture Evidence First
| Check | What to record |
|---|---|
| [ ] Verbose trace | Which agent, which tool, which thought loops |
| [ ] Per-task outputs | result.tasks_output raw text |
| [ ] Token usage | result.token_usage / crew.usage_metrics |
| [ ] Inputs | Exact kickoff(inputs=...) payload |
| [ ] Process mode | sequential vs hierarchical |
| [ ] Caps | max_iter, max_execution_time, max_rpm, retries |
Without artifacts you will tune folklore.
B - Task Contract Failures (Most Common)
| Symptom | Likely cause | Fix |
|---|---|---|
| Agent rambles / never "finishes" | Weak or missing expected_output | Write measurable acceptance text |
| Writer invents research | Missing context=[research_task] | Wire context; forbid tools on writer |
| Every task restates the whole mission | Descriptions too broad | Split tickets; one outcome each |
Placeholder leftovers like {topic} | Inputs not passed | Pass kickoff(inputs={"topic": ...}) |
| Output format wars | Contradictory description vs expected_output | Make them agree |
Litmus test: could a human contractor finish the task without chatting back? If not, the task is not ready for a crew.
C - Role and Tool Thrash
| Symptom | Likely cause | Fix |
|---|---|---|
| Two agents do the same search | Overlapping goals + shared tools | Least-privilege tool lists |
| Agent calls the same tool with tiny arg changes | Bad tool errors or vague description | Return clear errors; tighten tool docs |
| Delegation ping-pong | allow_delegation=True without need | Default false on workers |
| "I need more info" loops | Goal asks for perfection | Goal: best-effort under caps |
| Tool auth failures every turn | Missing env secrets | Fix credentials; fail fast |
D - Process-Specific Issues
Sequential
| Symptom | Fix |
|---|---|
| Stage N ignores stage N-1 | Add context; shrink stage N-1 into structured notes |
| Early stage dumps a novel | Cap length in expected_output ("max 15 bullets") |
| Late stage cannot recover bad notes | Add a thin normalize task; do not hope |
Hierarchical
| Symptom | Fix |
|---|---|
| Manager reassigns endlessly | Clarify worker roles; strengthen manager goal to stop criteria |
| Manager does the work itself poorly | Provide capable workers; constrain manager to assign/review |
| Missing manager config errors | Set manager_llm or manager_agent |
| Cost explosion | Cap iterations; switch stable pipelines back to sequential |
E - Stop Rails Checklist
- Agent
max_iterset intentionally (default may be higher than you want for demos). -
max_execution_timeon long tool users. -
max_retry_limitnot hiding persistent tool bugs. - Crew
max_rpmif provider 429s cause silent stalls/retries. - Product budget (wall clock + dollars) outside the framework.
-
respect_context_windowunderstood (summarization vs hard fail).
Prompts do not stop runaway loops. Host caps do.
F - Memory / Knowledge Confusion
| Symptom | Fix |
|---|---|
| Answers cite stale facts | Reset memory/knowledge in dev; check storage dir |
| Irrelevant recalls derail tasks | Narrow scopes; tune thresholds; disable memory to A/B |
| Embed dimension errors | Pin embedder; reset stores after model changes |
| Believes chat history is memory | Wire the correct layer (context vs Memory vs Knowledge) |
G - Minimal Bisect Procedure
- Single agent, single task with the same goal. If this fails, do not debug multi-agent yet.
- Add second agent without tools and explicit context. Confirm handoff text quality.
- Add one tool to the discoverer only.
- Enable memory only after the pipeline converges cold.
- Try hierarchical last, never first, when debugging convergence.
H - Logging Snippets
crew = Crew(
agents=[...],
tasks=[...],
verbose=True,
output_log_file="debug_crew.json",
)
result = crew.kickoff(inputs={"topic": "convergence debugging"})
for t in result.tasks_output:
print("====", getattr(t, "agent", None))
print((t.raw or "")[:1000])
print("tokens", result.token_usage)Replay mindset (CLI - verify at build): inspect latest task outputs, then crewai replay -t <task_id> after fixing a downstream task instead of re-running expensive upstream research.
I - When It Is Not a Crew Bug
- Provider outages / rate limits (check raw API errors).
- Model too weak for tool schemas (upgrade or simplify tools).
- Eval expects creativity but task demands strict format (align metrics).
- Human requirements still ambiguous (no framework fixes that).
FAQs
What does "converge" mean here?
The crew produces an acceptable final artifact within iteration/time/cost caps without repetitive no-progress cycles.
Should I raise max_iter to fix loops?
No as a first move. Raising caps hides the bug and increases spend. Fix tasks and tools first.
Why does verbose show clever thoughts but bad outputs?
Thought text is not graded. expected_output and tool results are. Tighten the contract and tool reliability.
Can hierarchical process reduce thrash?
Sometimes, when you need review. Often it adds thrash if workers already form a clean pipeline.
How do I detect no-progress loops programmatically?
Log tool name+args hashes and task output hashes; stop or alert when duplicates exceed a threshold.
Is planning a fix for non-convergence?
Rarely by itself. Planning helps organization; it cannot repair contradictory goals or broken tools.
Should I switch models while debugging?
Only after contracts are clear. Otherwise you cannot tell prompt bugs from model gaps.
What output should CI assert?
Structured fields or checklist items from expected_output, plus max token/time budgets, not full prose equality.
Do callbacks help?
Yes. step_callback / task_callback can emit metrics the terminal scrollback loses.
When should I abandon multi-agent?
When a single agent with one or two tools meets quality targets cheaper. Multi-agent is a cost, not a badge.
Related
- CrewAI Basics - minimal working crew
- Defining Agent Roles, Goals, and Backstories - fix role overlap
- Sequential vs Hierarchical Crew Processes - process misfile
- Building a Custom Tool for a CrewAI Agent - tool errors and schemas
- CrewAI 1.14's Pluggable Memory, Knowledge, and RAG Backends - stale recall issues
- CrewAI Best Practices - prevention checklist
Stack versions: Pins from the category manifest (verify at build): OpenRouter (~315+ models, July 2026 pricing/fees); LangGraph 1.0+; CrewAI 1.14+; Microsoft Agent Framework 1.0; Vercel AI SDK 6; Pydantic AI (latest); LlamaIndex (latest); OpenAI Agents SDK (latest + MCP); MCP (Linux Foundation governance); A2A (HTTP+SSE+JSON-RPC 2.0); Solana
@solana/web3.js+@solana/spl-token.