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

TavilyResearchTool._run raises this ValueError when self._client is None before calling client.research(...) to create/stream a Tavily research task. The client only exists if tavily-python was importable at __init__ time, so None indicates a tool built without its dependency (or with a swallowed init failure).

Source

Thrown at lib/crewai-tools/src/crewai_tools/tools/tavily_research_tool/tavily_research_tool.py:148

                )

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

    def _run(
        self,
        input: str,
        model: Literal["mini", "pro", "auto"] | None = None,
        output_schema: dict[str, Any] | None = None,
        stream: bool | None = None,
        citation_format: Literal["numbered", "mla", "apa", "chicago"] | None = None,
    ) -> str | Generator[bytes, None, None]:
        """Synchronously creates Tavily research tasks or streams results."""
        if not self._client:
            raise ValueError(
                "Tavily client is not initialized. Ensure 'tavily-python' is "
                "installed and API key is set."
            )

        use_stream = self.stream if stream is None else stream
        result = self._client.research(
            input=input,
            model=self.model if model is None else model,
            output_schema=self.output_schema
            if output_schema is None
            else output_schema,
            stream=use_stream,
            citation_format=(
                self.citation_format if citation_format is None else citation_format
            ),
        )

        if use_stream:

View on GitHub (pinned to 754d7323be)

Solutions

Install tavily-python and set TAVILY_API_KEY, then create a fresh TavilyResearchTool.
Assert tool._client is not None before invoking run().
Rebuild tools after any environment/dependency change instead of reusing instances.

Example fix

# before
out = tool._run("research quantum error correction")  # -> ValueError

# after
if not tool._client:
    tool = TavilyResearchTool()
out = tool._run("research quantum error correction")

Defensive patterns

Strategy: type-guard

Validate before calling

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

Type guard

def 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(input="...")
except ValueError as e:
    if "Tavily client is not initialized" in str(e):
        tool = TavilyResearchTool()
        out = tool._run(input="...")
    else:
        raise

Prevention

Verify tavily-python import and TAVILY_API_KEY before tool construction.
Guard on _client before run(); rebuild the tool if it is None.
Never reuse tool instances across dependency/environment changes.

When it happens

Trigger: Invoking tool.run(input=..., model=..., stream=...) on an instance whose __init__ never built a TavilyClient — tavily-python missing at construction, or init interrupted.

Common situations: Stale tool instances from before the package was installed; TAVILY_API_KEY missing at construction in code paths that assume lazy init.

Related errors

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