crewAIInc/crewAI · error · ValueError

Tavily async client is not initialized. Ensure 'tavily-pytho

Error message

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

What it means

TavilySearchTool._run asynchronously (arun) guards on self.async_client. The AsyncTavilyClient is only constructed at init when tavily-python imported successfully and an API key (constructor arg or TAVILY_API_KEY) was present. If not, async_client is None and awaits fail with ValueError.

Source

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

                        )

        return json.dumps(raw_results, indent=2)

    async def _arun(
        self,
        query: str,
    ) -> str:
        """Asynchronously 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.async_client:
            raise ValueError(
                "Tavily async client is not initialized. Ensure 'tavily-python' is installed and API key is set."
            )

        raw_results = await self.async_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

Provide the key at construction (api_key=...) or export TAVILY_API_KEY before building the tool.
Confirm tavily-python is installed in the runtime environment and the app was restarted after installation.
Initialize environment config at process start (before any tool/crew construction).

Example fix

# before
async def main():
    await tool.arun('query')  # async_client is None -> ValueError

# after
import os
os.environ.setdefault('TAVILY_API_KEY', 'tvly-...')  # or load_dotenv() first
tool = TavilySearchTool()
async def main():
    await tool.arun('query')

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'), 'TAVILY_API_KEY not set'
# async client will be constructed at init

Type guard

def tavily_async_ready(tool) -> bool:
    return tool.async_client is not None

Try / catch

try:
    result = await tool.arun(query)
except ValueError as e:
    if 'async client is not initialized' in str(e):
        raise SystemExit(f'Fix TAVILY_API_KEY/install, then restart: {e}')
    raise

Prevention

Initialize env/config once at process start, before async event loops create tools.
Assert tool.async_client is not None right after construction in async apps.
Include tavily-python in the deployment image, not installed at runtime.

When it happens

Trigger: Awaiting tool.arun(query) / tool._run(query) in async code when the tool was constructed without an API key or without tavily-python available, so the async client was never created.

Common situations: Async CrewAI crews where the .env was loaded after tool creation; deploying to an environment missing TAVILY_API_KEY; restarting after interactive install was skipped.

Related errors

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