When a CrewAI agent stuck debugging a multi-step workflow, the hang rarely traces to a single broken model call. More often, an unbounded tool, silent delegation loop, or provider rate limit leaves the crew waiting on a future that never resolves.
Step 1: Reproduce with Maximum Verbosity and Structured Logging
CrewAI swallows intermediate reasoning unless you force it out. Set verbose=2 on every agent and the crew, and capture the final output from kickoff(). Without this, you are flying blind.
from crewai import Agent, Task, Crew, Process
researcher = Agent(
role="researcher",
goal="find API docs",
backstory="expert",
verbose=2,
)
writer = Agent(
role="writer",
goal="summarize",
backstory="prose",
verbose=2,
)
task = Task(description="Fetch and summarize", expected_output="markdown")
crew = Crew(
agents=[researcher, writer],
tasks=[task],
process=Process.sequential,
verbose=2,
)
result = crew.kickoff()
print(result)Run this and watch which agent prints its last thought. If the log stops after a tool call, the stall is in that tool. If it stops before any agent action, the LLM call itself is blocking.
Verify success: you see per-agent <AgentName> Task: ... lines and a final Crew Output: block. If the script exits without the block, you have reproduced the stall.
Step 2: Isolate the Stall with Per-Tool Timeouts
Most mid-task freezes come from a requests call or subprocess that never returns. CrewAI does not impose a wall-clock limit on custom tools. Wrap every I/O boundary.
from crewai_tools import tool
import requests
from concurrent.futures import ThreadPoolExecutor, TimeoutError as FuturesTimeout
@tool("fetch_url")
def fetch_url(url: str) -> str:
"""Fetch a URL with a 10s timeout."""
def _get():
return requests.get(url, timeout=10).text[:2000]
with ThreadPoolExecutor(max_workers=1) as ex:
future = ex.submit(_get)
try:
return future.result(timeout=12)
except FuturesTimeout:
return "ERROR: tool timed out"Returning a string error instead of raising keeps the agent alive and lets it reason about the failure. A hanging tool will now surface as a visible error in the verbose log.
Verify success: replace a suspect tool with the timeout wrapper and rerun. The crew should either complete or log ERROR: tool timed out rather than hang for minutes.
Step 3: Check Agent Delegation and Max Iterations
CrewAI agents can delegate tasks to peers. A misconfigured delegation target or a vague goal creates a loop: agent A delegates to B, B delegates back to A. The crew burns iterations and then silently stops.
Cap the loop explicitly:
from crewai import Agent
agent = Agent(
role="researcher",
goal="...",
backstory="...",
max_iter=8,
max_retry_limit=3,
allow_delegation=False, # turn off if not needed
verbose=2,
)If you need delegation, set max_iter low (5–10) and watch the iteration counter in logs. When the counter hits the cap, CrewAI raises MaxIterationsExceededError instead of stalling.
Verify success: intentionally create a circular delegate (two agents with allow_delegation=True and conflicting goals). With caps set, the run fails fast with a clear exception rather than hanging.
Step 4: Inspect Context Window and Output Parsing
A stall often follows a sudden truncation. The model receives a context longer than its limit, the provider silently drops older messages, and the agent responds with malformed JSON or an empty string. CrewAI then waits for a parse that never matches expected_output.
Disable memory and caching during debugging to shrink context:
agent = Agent(
role="writer",
goal="...",
backstory="...",
memory=False,
cache=False,
verbose=2,
)
task = Task(
description="...",
expected_output="valid JSON",
output_json={"summary": str, "confidence": float},
)Using output_json forces a schema check. If the model returns garbage, CrewAI logs a parsing failure instead of blocking.
Verify success: run with a deliberately oversized input. With memory=False and schema enforcement, you get a parse error in seconds, not a hang.
Step 5: Swap the LLM Endpoint to Surface Provider-Level Faults
Provider rate limits and partial degradations are a common but invisible cause of a CrewAI agent stuck debugging a task. The default OpenAI client retries with exponential backoff that can exceed your patience.
Point CrewAI at an OpenAI-compatible gateway that fails over automatically. For example, n4n.ai exposes one OpenAI-compatible endpoint covering 240+ models and applies automatic fallback when a provider is rate-limited or degraded, converting a silent stall into a quick reroute.
from crewai import LLM
llm = LLM(
model="openai/gpt-4o-mini",
base_url="https://api.n4n.ai/v1",
api_key="YOUR_KEY",
timeout=30,
)
agent = Agent(role="...", goal="...", backstory="...", llm=llm, verbose=2)The timeout parameter bounds the request. If the primary provider is throttled, the gateway returns a different provider’s response without the crew noticing.
Verify success: artificially throttle your API key at the provider (or pull the network). The crew should still finish because the gateway routes around the failure.
Step 6: Execute Agents and Tasks in Isolation
Before running the full crew, call each agent’s execute_task directly. This removes inter-agent handoff from the equation.
from crewai import Agent, Task
agent = Agent(role="researcher", goal="...", backstory="...", verbose=2)
task = Task(description="Fetch X", expected_output="text")
output = agent.execute_task(task)
print("ISOLATED OUTPUT:", output)If isolation works but the crew hangs, the problem is in Process coordination—usually a shared tool or a cache collision. If isolation also hangs, the fault is in the agent/tool/LLM trio from Steps 2–5.
Verify success: both isolated calls return within your timeout. The full crew then has a much smaller surface area to debug.
Step 7: Enforce a Hard Wall-Clock Timeout on Kickoff
As a last line of defense, run crew.kickoff() inside a worker with a hard kill. Python’s signal works on the main thread; for threads use multiprocessing.
import multiprocessing
def run_crew(q):
try:
res = crew.kickoff()
q.put(("ok", res))
except Exception as e:
q.put(("err", str(e)))
if __name__ == "__main__":
q = multiprocessing.Queue()
p = multiprocessing.Process(target=run_crew, args=(q,))
p.start()
p.join(timeout=120) # hard 2-minute cap
if p.is_alive():
p.terminate()
print("CREW KILLED: exceeded 120s")
else:
print(q.get())This guarantees the process never hangs your pipeline, and the terminate path tells you the stall was wall-clock bound.
Verify success: set timeout=5 with a known slow tool. The script prints CREW KILLED instead of running indefinitely.
How to Verify Success
A debugged crew meets four criteria: (1) verbose logs show every agent step and tool call; (2) no tool or LLM call exceeds its declared timeout; (3) iteration caps trigger explicit errors instead of silent loops; (4) a full kickoff() completes under your hard wall-clock limit. Run the isolated agent tests from Step 6, then the full crew with the Step 7 guard. If both pass, the CrewAI agent stuck debugging issue is resolved.