CrewAI

Common errors

• OPENAI_API_KEY is required

  cause CrewAI, or its underlying dependencies like `litellm`, often defaults to requiring an OpenAI API key for validation, even when a different LLM provider or local model is intended for use.
  fix If using OpenAI, ensure your `OPENAI_API_KEY` is set as an environment variable or in a `.env` file. If using another LLM (e.g., Groq, Ollama, Google Generative AI), explicitly pass the `llm` parameter to your agents and crew. You might still need to set a dummy `OPENAI_API_KEY="sk-dummy"` in your `.env` file to bypass initial validation if the error persists.

• ModuleNotFoundError: No module named 'tiktoken'

  cause The `tiktoken` library, essential for tokenization with many LLMs and often required for embeddings, is a dependency that might not be automatically installed with the base `crewai` package or if specific 'extras' like `[embeddings]` or `[tools]` were omitted during installation.
  fix Install `tiktoken` explicitly. It's often beneficial to install it along with the `crewai[embeddings]` or `crewai[tools]` extras to ensure all related dependencies are met: `pip install 'crewai[embeddings]'` or `pip install tiktoken`.

• AttributeError: 'list' object has no attribute 'get'

  cause This error typically occurs when a list is provided in a context where a dictionary is expected, and the code attempts to call the `.get()` method (which is a dictionary method) on that list. This often happens with malformed YAML configurations for agents or tasks.
  fix Review your agent and task definitions, especially if loading from YAML files. Ensure that where dictionaries are expected (e.g., for agent configurations), you are providing a dictionary-like structure and not a list. Check for incorrect indentation or syntax in your YAML.

• ModuleNotFoundError: No module named 'crewai'

  cause The `crewai` library has not been installed in your current Python environment, or the environment where it was installed is not active.
  fix Install the `crewai` package using pip in your active Python environment: `pip install crewai`.

• Agent stopped due to iteration limit or time limit.

  cause An agent has exceeded the configured maximum number of iterations (`max_iter`) or the maximum allowed execution time (`max_execution_time`) while attempting to complete its assigned task. This can occur with complex tasks, less capable LLMs, or insufficient default limits.
  fix Increase the `max_iter` and/or `max_execution_time` parameters when initializing your agent. For example, `Agent(..., max_iter=25, max_execution_time=120)`. If the problem persists, consider using a more powerful LLM or breaking down the task into simpler, more manageable sub-tasks.

Warnings

• breaking Python <3.10 is not supported. CrewAI requires Python >=3.10 and <3.14. Installation on 3.9 will fail or produce broken behavior.
  Fix: Use Python 3.10, 3.11, or 3.12. Python 3.13 is supported but 3.14 is not yet.
• breaking Task.expected_output is a required field. Omitting it raises a validation error at instantiation time.
  Fix: Always specify expected_output in every Task definition, even if just a short description string.
• breaking crewai-tools is a completely separate package from crewai. Tools like SerperDevTool, FileReadTool, and WebsiteSearchTool raise ImportError if crewai-tools is not installed separately.
  Fix: pip install crewai-tools (or pip install 'crewai-tools[mcp]' for MCP support)
• breaking The recommended project structure uses YAML config files (src/<project>/config/agents.yaml and tasks.yaml) with @CrewBase, @agent, @task decorators. Code-only setups from older tutorials (pre-1.0) are still valid but the YAML-first pattern is now canonical and most docs assume it.
  Fix: Use 'crewai create crew <name>' CLI command to scaffold the correct project structure with YAML configs.
• breaking The crewai-tools repo (crewAIInc/crewAI-tools on GitHub) is now archived. Tool development has moved to the crewai-tools PyPI package maintained in the main crewai ecosystem.
  Fix: Install from PyPI: pip install crewai-tools. Do not use the archived GitHub repo directly.
• gotcha Small open-source models (7B and below) often fail at function/tool calling within CrewAI. The framework relies heavily on the LLM's ability to generate correctly structured tool calls.
  Fix: Use models with strong tool-call support: GPT-4o, Claude 3.5+, Gemini 2.0+, or Qwen3-72B+ for reliable agentic behavior.
• gotcha Windows users encounter build errors for chroma-hnswlib==0.7.6 (a memory dependency) due to missing C++ build tools.
  Fix: Install Visual Studio Build Tools with the 'Desktop development with C++' workload before pip install crewai.
• gotcha crew.kickoff() is synchronous and blocking. For async contexts or FastAPI use, use crew.kickoff_async() instead.
  Fix: await crew.kickoff_async(inputs={...}) in async contexts.
• gotcha Non-OpenAI LLM providers require litellm and the correct model string format: 'provider/model-name' (e.g. 'anthropic/claude-sonnet-4-5', 'ollama/gemma3'). Passing just the model name without provider prefix silently routes to OpenAI.
  Fix: Use LLM(model='anthropic/claude-sonnet-4-5', api_key=...) or set the MODEL env var to 'provider/model-name'.

Install

• pip install crewai Core framework
• pip install crewai-tools Optional: pre-built tools (SerperDevTool, FileReadTool, WebsiteSearchTool, etc.)
• pip install 'crewai-tools[mcp]' Optional: MCP server tool support

Imports

• Agent, Task, Crew
  wrong:

  from crewai import *

  correct:

  from crewai import Agent, Task, Crew, Process
  from crewai import LLM

  Core classes are in the crewai package. Tools (SerperDevTool etc.) are in the separate crewai_tools package.
• crewai_tools
  wrong:

  from crewai import SerperDevTool

  correct:

  from crewai_tools import SerperDevTool, FileReadTool

  crewai_tools is a separate pip package. It is NOT included with pip install crewai.

Quickstart

Minimal two-agent crew with sequential process

from crewai import Agent, Task, Crew, Process

researcher = Agent(
    role='Senior Researcher',
    goal='Uncover groundbreaking technologies in AI',
    backstory='You are an expert researcher with a passion for AI innovation.',
    verbose=True
)

writer = Agent(
    role='Tech Writer',
    goal='Craft compelling articles about AI discoveries',
    backstory='You are a skilled writer who makes complex topics accessible.',
    verbose=True
)

research_task = Task(
    description='Research the latest breakthroughs in AI for 2026.',
    expected_output='A list of 5 key AI breakthroughs with brief descriptions.',
    agent=researcher
)

write_task = Task(
    description='Write a short article based on the research findings.',
    expected_output='A 3-paragraph article in markdown format.',
    agent=writer
)

crew = Crew(
    agents=[researcher, writer],
    tasks=[research_task, write_task],
    process=Process.sequential,
    verbose=True
)

result = crew.kickoff()
print(result)