crewAIInc/crewAI · error · ValueError

Tavily client is not initialized. Ensure 'tavily-python' is

Error message

Tavily client is not initialized. Ensure 'tavily-python' is installed and API key is set.

What it means

TavilySearchTool._run() guards on self.client before searching. The synchronous Tavily client only gets constructed at init when the tavily-python import succeeded AND a usable API key was found (constructor argument or TAVILY_API_KEY env var). If either precondition failed, client stays None and _run raises ValueError.

Source

Thrown at lib/crewai-tools/src/crewai_tools/tools/tavily_search_tool/tavily_search_tool.py:168

                    "The 'tavily-python' package is required to use the TavilySearchTool. "
                    "Please install it with: uv add tavily-python"
                )

    def _run(
        self,
        query: str,
    ) -> str:
        """Synchronously performs a search using the Tavily API.
        Content of each result is truncated to `max_content_length_per_result`.

        Args:
            query: The search query string.

        Returns:
            A JSON string containing the search results with truncated content.
        """
        if not self.client:
            raise ValueError(
                "Tavily client is not initialized. Ensure 'tavily-python' is installed and API key is set."
            )

        raw_results = self.client.search(
            query=query,
            search_depth=self.search_depth,
            topic=self.topic,
            time_range=self.time_range,
            days=self.days,
            max_results=self.max_results,
            include_domains=self.include_domains,
            exclude_domains=self.exclude_domains,
            include_answer=self.include_answer,
            include_raw_content=self.include_raw_content,
            include_images=self.include_images,
            timeout=self.timeout,
        )

View on GitHub (pinned to 754d7323be)

Solutions

Set the key explicitly: TavilySearchTool(api_key='tvly-...') or export TAVILY_API_KEY='tvly-...' before creating the tool.
Verify tavily-python is importable in the running interpreter (python -c 'import tavily') and restart the app after any install.
Load .env early via load_dotenv() before constructing the tool.
Fail fast at startup: assert the env var exists before building the crew.

Example fix

# before
tool = TavilySearchTool()  # no TAVILY_API_KEY in env
tool.run('latest AI news')  # ValueError: client not initialized

# after
import os
from dotenv import load_dotenv
load_dotenv()
assert os.getenv('TAVILY_API_KEY'), 'TAVILY_API_KEY missing'
tool = TavilySearchTool()  # client built at init
tool.run('latest AI news')

Defensive patterns

Strategy: validation

Validate before calling

import os, importlib.util
assert importlib.util.find_spec('tavily'), 'tavily-python not installed'
assert os.getenv('TAVILY_API_KEY') or args.get('api_key'), 'TAVILY_API_KEY not set'
# now safe to construct and call TavilySearchTool

Type guard

def tavily_ready(tool) -> bool:
    return tool.client is not None

Try / catch

try:
    result = tool.run(query)
except ValueError as e:
    if 'not initialized' in str(e):
        # config bug, not transient - fix env and rebuild the tool
        raise SystemExit(f'TavilySearchTool misconfigured: {e}')
    raise

Prevention

Set TAVILY_API_KEY in the environment or pass api_key at construction, verified at startup.
Load .env before any crew/tool construction.
Treat a None client as a build-time failure: assert tool.client after construction.

When it happens

Trigger: Calling tool.run(...) or tool._run(query) when tavily-python was unavailable at construction time, or when neither the api_key constructor argument nor the TAVILY_API_KEY environment variable was provided/set to a non-empty value.

Common situations: Forgetting to export TAVILY_API_KEY in the shell/CI that runs the crew; passing an empty-string api_key; the interactive install path deferred the client so a restart never happened; .env file not loaded before tool construction.

Related errors

AI-assisted analysis of crewAIInc/crewAI@754d7323be (2026-08-15). Data as JSON: /api/errors/08e32adb7b516ff9. Report an issue: GitHub.