How to Fix 'timeout error' in CrewAI (Python)

A timeout error in CrewAI usually means one of your agent calls took longer than the configured limit, or the underlying LLM request never returned in time. It typically shows up when an agent is doing too much work in one step, the model is slow, or your tool call hangs and blocks the task pipeline.

In practice, this is almost always a timeout at one of three layers:

• •CrewAI task execution
• •The LLM client request
• •A tool or API call inside an agent step

The Most Common Cause

The #1 cause is a long-running task with no timeout tuning, usually combined with a slow model or an overworked tool. In CrewAI, this often surfaces as something like:

• •TimeoutError: Request timed out
• •litellm.exceptions.TimeoutError
• •crewai.exceptions.TaskExecutionError: Error executing task

Here’s the broken pattern I see most often: one agent is asked to do too much in a single task, and the default request timeout gets hit.

# BROKEN
from crewai import Agent, Task, Crew
from crewai.llm import LLM

researcher = Agent(
    role="Researcher",
    goal="Analyze the entire market and produce a full report",
    backstory="Senior analyst",
    llm=LLM(model="gpt-4o")
)

task = Task(
    description="""
    Research every competitor in the insurance market,
    summarize all pricing models, extract risks,
    compare product lines, and write a full report.
    """,
    agent=researcher
)

crew = Crew(agents=[researcher], tasks=[task])
result = crew.kickoff()

# FIXED
from crewai import Agent, Task, Crew
from crewai.llm import LLM

researcher = Agent(
    role="Researcher",
    goal="Analyze competitor pricing for one segment at a time",
    backstory="Senior analyst",
    llm=LLM(model="gpt-4o", timeout=120)  # explicit request timeout
)

task = Task(
    description="""
    Research only auto insurance competitors for small businesses.
    Return 5 bullet points with pricing signals and risks.
    """,
    agent=researcher,
)

crew = Crew(agents=[researcher], tasks=[task])
result = crew.kickoff()

If you’re calling external tools, add a timeout there too. A slow API inside a tool will look like a CrewAI timeout even though the real problem is downstream.

import requests
from crewai.tools import BaseTool

class PricingTool(BaseTool):
    name = "pricing_tool"
    description = "Fetch competitor pricing"

    def _run(self, query: str) -> str:
        response = requests.get(
            "https://api.example.com/pricing",
            params={"q": query},
            timeout=20,
        )
        response.raise_for_status()
        return response.text

Other Possible Causes

1. Model latency or overloaded provider

Sometimes your code is fine and the model provider is just slow. This happens more with large prompts, high token output, or peak traffic.

# Reduce output size and use a faster model if needed
llm = LLM(
    model="gpt-4o-mini",
    temperature=0.2,
    max_tokens=800,
)

2. A tool that never returns

A custom tool can hang on network calls, file I/O, or infinite loops. CrewAI waits for the tool result, so one bad tool blocks the whole task.

# BAD: no timeout
data = requests.get(url).text

# GOOD: bounded request time
data = requests.get(url, timeout=15).text

3. Task context too large

If you keep passing long conversation history or massive documents between tasks, the prompt can become expensive and slow enough to trigger timeouts.

# Trim context before passing it forward
summary_task = Task(
    description="Summarize only key findings in 10 bullets.",
    agent=researcher,
)

4. Nested delegation creating long chains

If agents keep delegating work to each other without tight limits, you can end up with a long execution chain that exceeds time limits.

manager = Agent(
    role="Manager",
    goal="Delegate only once per issue",
    allow_delegation=True,
)

How to Debug It

1. •

   Check where the exception is thrown

   • •If you see litellm.exceptions.TimeoutError, it’s usually the LLM call.
   • •If you see crewai.exceptions.TaskExecutionError, inspect the underlying exception chain.
2. •

   Run one task at a time

   • •Disable multi-agent flows temporarily.
   • •Confirm whether the failure happens on a specific task or tool.
3. •

   Instrument your tools

   • •Add logs before and after each external API call.
   • •Measure elapsed time so you know whether the delay is in your code or upstream.

import time

start = time.time()
result = my_tool.run("query")
print(f"tool took {time.time() - start:.2f}s")

4. •Lower complexity
   • •Shorten prompts.
   • •Reduce max output tokens.
   • •Switch to a faster model.
   • •Remove delegation until the base path works.

Prevention

• •Set explicit timeouts on both your LLM client and every external API call.
• •Keep each CrewAI task narrow and bounded; don’t ask one agent to do an entire project in one shot.
• •Add observability around agent steps so you can tell whether failures come from CrewAI, the model provider, or your tools.

If you want stable production behavior, treat every agent step like an API boundary. Bound it, log it, and fail fast when it exceeds budget.

Keep learning

• •The complete AI Agents Roadmap — my full 8-step breakdown
• •Free: The AI Agent Starter Kit — PDF checklist + starter code
• •Work with me — I build AI for banks and insurance companies

By Cyprian Aarons, AI Consultant at Topiax.