{"record":{"id":"08e32adb7b516ff9","repo":"crewAIInc/crewAI","slug":"tavily-client-is-not-initialized-ensure-tavily-p-08e32a","errorCode":null,"errorMessage":"Tavily client is not initialized. Ensure 'tavily-python' is installed and API key is set.","messagePattern":"Tavily client is not initialized\\. Ensure 'tavily-python' is installed and API key is set\\.","errorType":"exception","errorClass":"ValueError","httpStatus":null,"severity":"error","filePath":"lib/crewai-tools/src/crewai_tools/tools/tavily_search_tool/tavily_search_tool.py","lineNumber":168,"sourceCode":"                    \"The 'tavily-python' package is required to use the TavilySearchTool. \"\n                    \"Please install it with: uv add tavily-python\"\n                )\n\n    def _run(\n        self,\n        query: str,\n    ) -> str:\n        \"\"\"Synchronously performs a search using the Tavily API.\n        Content of each result is truncated to `max_content_length_per_result`.\n\n        Args:\n            query: The search query string.\n\n        Returns:\n            A JSON string containing the search results with truncated content.\n        \"\"\"\n        if not self.client:\n            raise ValueError(\n                \"Tavily client is not initialized. Ensure 'tavily-python' is installed and API key is set.\"\n            )\n\n        raw_results = self.client.search(\n            query=query,\n            search_depth=self.search_depth,\n            topic=self.topic,\n            time_range=self.time_range,\n            days=self.days,\n            max_results=self.max_results,\n            include_domains=self.include_domains,\n            exclude_domains=self.exclude_domains,\n            include_answer=self.include_answer,\n            include_raw_content=self.include_raw_content,\n            include_images=self.include_images,\n            timeout=self.timeout,\n        )\n","sourceCodeStart":150,"sourceCodeEnd":186,"githubUrl":"https://github.com/crewAIInc/crewAI/blob/754d7323beb2fd042e33444a115ea2d5a47193f0/lib/crewai-tools/src/crewai_tools/tools/tavily_search_tool/tavily_search_tool.py#L150-L186","documentation":"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.","triggerScenarios":"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.","commonSituations":"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.","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."],"exampleFix":"# before\ntool = TavilySearchTool()  # no TAVILY_API_KEY in env\ntool.run('latest AI news')  # ValueError: client not initialized\n\n# after\nimport os\nfrom dotenv import load_dotenv\nload_dotenv()\nassert os.getenv('TAVILY_API_KEY'), 'TAVILY_API_KEY missing'\ntool = TavilySearchTool()  # client built at init\ntool.run('latest AI news')","handlingStrategy":"validation","validationCode":"import os, importlib.util\nassert importlib.util.find_spec('tavily'), 'tavily-python not installed'\nassert os.getenv('TAVILY_API_KEY') or args.get('api_key'), 'TAVILY_API_KEY not set'\n# now safe to construct and call TavilySearchTool","typeGuard":"def tavily_ready(tool) -> bool:\n    return tool.client is not None","tryCatchPattern":"try:\n    result = tool.run(query)\nexcept ValueError as e:\n    if 'not initialized' in str(e):\n        # config bug, not transient - fix env and rebuild the tool\n        raise SystemExit(f'TavilySearchTool misconfigured: {e}')\n    raise","preventionTips":["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."],"tags":["configuration","api-key","environment","tavily"],"backgroundTag":null,"analyzedSha":"754d7323beb2fd042e33444a115ea2d5a47193f0","analyzedAt":"2026-08-15T04:06:56.746Z","schemaVersion":2},"datasetVersion":"2026-08-15T22:17:37.221Z"}