{"record":{"id":"a3645f3c1a92d79f","repo":"crewAIInc/crewAI","slug":"the-couchbase-package-is-required-to-use-the-cou","errorCode":null,"errorMessage":"The 'couchbase' package is required to use the CouchbaseFTSVectorSearchTool. Please install it with: uv add couchbase","messagePattern":"The 'couchbase' package is required to use the CouchbaseFTSVectorSearchTool\\. Please install it with: uv add couchbase","errorType":"exception","errorClass":"ImportError","httpStatus":null,"severity":"error","filePath":"lib/crewai-tools/src/crewai_tools/tools/couchbase_tool/couchbase_tool.py","lineNumber":180,"sourceCode":"                raise ValueError(\n                    f\"Bucket {self.bucket_name} does not exist. \"\n                    \" Please create the bucket before searching.\"\n                )\n\n            self._check_scope_and_collection_exists()\n            self._check_index_exists()\n        else:\n            import click\n\n            if click.confirm(\n                \"The 'couchbase' package is required to use the CouchbaseFTSVectorSearchTool. \"\n                \"Would you like to install it?\"\n            ):\n                import subprocess\n\n                subprocess.run([\"uv\", \"add\", \"couchbase\"], check=True)  # noqa: S607\n            else:\n                raise ImportError(\n                    \"The 'couchbase' package is required to use the CouchbaseFTSVectorSearchTool. \"\n                    \"Please install it with: uv add couchbase\"\n                )\n\n    def _run(self, query: str) -> str:\n        \"\"\"Execute a vector search query against the Couchbase index.\n\n        Args:\n            query: The search query string.\n\n        Returns:\n            A JSON string containing the search results.\n\n        Raises:\n            ValueError: If the search query fails or returns results without fields.\n        \"\"\"\n        query_embedding = self.embedding_function(query)\n        fields = [\"*\"]","sourceCodeStart":162,"sourceCodeEnd":198,"githubUrl":"https://github.com/crewAIInc/crewAI/blob/754d7323beb2fd042e33444a115ea2d5a47193f0/lib/crewai-tools/src/crewai_tools/tools/couchbase_tool/couchbase_tool.py#L162-L198","documentation":"CouchbaseFTSVectorSearchTool optionally depends on the couchbase package. At import time the tool checks COUCHBASE_AVAILABLE; when it is False it prompts via click.confirm('...install it?'). If you decline (or run non-interactively where confirm defaults to No), the tool raises this ImportError telling you to install the package with 'uv add couchbase'.","triggerScenarios":"Instantiating CouchbaseFTSVectorSearchTool in an environment where 'import couchbase' failed (package not installed, wrong venv), and answering 'n' to the interactive install prompt, or running headless (CI, agent runtime) where click.confirm cannot prompt and returns the default. The uv-subprocess install path can also fail when uv is not on PATH, leading to the same branch.","commonSituations":"Using crewai-tools extras without installing the couchbase optional dependency; running inside a Docker/CI container with no TTY so click.confirm auto-declines; multiple virtualenvs where the tool runs in an env lacking couchbase.","solutions":["Install the dependency into the active environment: uv add couchbase (or pip install couchbase).","If it should already be installed, verify you are running in the same interpreter/venv the tool is imported from (python -c \"import couchbase\").","For Docker/CI images, add couchbase to the image dependencies so the interactive prompt is never reached.","If you answered 'n' to the prompt by mistake, just rerun after installing the package."],"exampleFix":"# before (interactive prompt declined / headless run)\ntool = CouchbaseFTSVectorSearchTool(...)  # ImportError\n\n# after\n# shell:\n#   uv add couchbase\ntool = CouchbaseFTSVectorSearchTool(...)  # works","handlingStrategy":"validation","validationCode":"def couchbase_available() -> bool:\n    try:\n        import couchbase  # noqa: F401\n        return True\n    except ImportError:\n        return False\n\nif not couchbase_available():\n    raise RuntimeError(\"Install couchbase before using CouchbaseFTSVectorSearchTool\")","typeGuard":null,"tryCatchPattern":"try:\n    tool = CouchbaseFTSVectorSearchTool(...)\nexcept ImportError as e:\n    if \"couchbase\" in str(e):\n        subprocess.run([\"uv\", \"add\", \"couchbase\"], check=True)\n        tool = CouchbaseFTSVectorSearchTool(...)\n    else:\n        raise","preventionTips":["Declare couchbase in your project dependencies instead of relying on the interactive prompt.","Headless environments (CI, Docker) never see the prompt — preinstall the package in the image.","Smoke-test 'import couchbase' in your entrypoint startup."],"tags":["couchbase","import","dependency","optional-dependency","uv"],"backgroundTag":null,"analyzedSha":"754d7323beb2fd042e33444a115ea2d5a47193f0","analyzedAt":"2026-08-15T04:06:56.746Z","schemaVersion":2},"datasetVersion":"2026-08-15T17:31:12.345Z"}