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

TavilyGetResearchTool._run raises this ValueError when self._client is None while trying to fetch a research task's status/results via client.get_research(request_id). _client is only built in __init__ when tavily-python is importable, so None means the package (or its client construction) was skipped.

Source

Thrown at lib/crewai-tools/src/crewai_tools/tools/tavily_get_research_tool/tavily_get_research_tool.py:105

                        f"Attempted to install 'tavily-python' but failed: {e}. "
                        "Please install it manually to use the TavilyGetResearchTool."
                    ) from e
            else:
                raise ImportError(
                    "The 'tavily-python' package is required to use the "
                    "TavilyGetResearchTool. Please install it with: uv add tavily-python"
                )

    @staticmethod
    def _stringify_response(response: Any) -> str:
        if isinstance(response, str):
            return response
        return json.dumps(response, indent=2)

    def _run(self, request_id: str) -> str:
        """Synchronously retrieves Tavily research task status and results."""
        if not self._client:
            raise ValueError(
                "Tavily client is not initialized. Ensure 'tavily-python' is "
                "installed and API key is set."
            )

        return self._stringify_response(self._client.get_research(request_id))

    async def _arun(self, request_id: str) -> str:
        """Asynchronously retrieves Tavily research task status and results."""
        if not self._async_client:
            raise ValueError(
                "Tavily async client is not initialized. Ensure 'tavily-python' is "
                "installed and API key is set."
            )

        return self._stringify_response(
            await self._async_client.get_research(request_id)
        )

View on GitHub (pinned to 754d7323be)

Solutions

  1. Install tavily-python and instantiate a fresh TavilyGetResearchTool.
  2. Verify TAVILY_API_KEY is set in the environment at construction time.
  3. Check tool._client before calling run(); rebuild the tool if it is None.

Example fix

# before
status = tool._run(req_id)  # -> ValueError: Tavily client is not initialized

# after
if not tool._client:
    tool = TavilyGetResearchTool()
status = tool._run(req_id)
Defensive patterns

Strategy: type-guard

Validate before calling

if not getattr(tool, "_client", None):
    raise RuntimeError("TavilyGetResearchTool uninitialized; rebuild after installing tavily-python")

Type guard

def get_research_ready(tool) -> bool:
    """True when the sync Tavily research client exists."""
    return getattr(tool, "_client", None) is not None

Try / catch

try:
    out = tool._run(request_id)
except ValueError as e:
    if "Tavily client is not initialized" in str(e):
        tool = TavilyGetResearchTool()
        out = tool._run(request_id)
    else:
        raise

Prevention

When it happens

Trigger: Calling tool.run(request_id)/_run on an instance created while tavily-python was missing, or where os.getenv("TAVILY_API_KEY") paths never ran; the guard fires before any Tavily API call.

Common situations: Reusing a tool instance created before the dependency was installed; half-initialized tools after a swallowed __init__ error.

Related errors

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