crewAIInc/crewAI · error · ImportError

The 'couchbase' package is required to use the CouchbaseFTSV

Error message

The 'couchbase' package is required to use the CouchbaseFTSVectorSearchTool. Please install it with: uv add couchbase

What it means

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'.

Source

Thrown at lib/crewai-tools/src/crewai_tools/tools/couchbase_tool/couchbase_tool.py:180

                raise ValueError(
                    f"Bucket {self.bucket_name} does not exist. "
                    " Please create the bucket before searching."
                )

            self._check_scope_and_collection_exists()
            self._check_index_exists()
        else:
            import click

            if click.confirm(
                "The 'couchbase' package is required to use the CouchbaseFTSVectorSearchTool. "
                "Would you like to install it?"
            ):
                import subprocess

                subprocess.run(["uv", "add", "couchbase"], check=True)  # noqa: S607
            else:
                raise ImportError(
                    "The 'couchbase' package is required to use the CouchbaseFTSVectorSearchTool. "
                    "Please install it with: uv add couchbase"
                )

    def _run(self, query: str) -> str:
        """Execute a vector search query against the Couchbase index.

        Args:
            query: The search query string.

        Returns:
            A JSON string containing the search results.

        Raises:
            ValueError: If the search query fails or returns results without fields.
        """
        query_embedding = self.embedding_function(query)
        fields = ["*"]

View on GitHub (pinned to 754d7323be)

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.

Example fix

# before (interactive prompt declined / headless run)
tool = CouchbaseFTSVectorSearchTool(...)  # ImportError

# after
# shell:
#   uv add couchbase
tool = CouchbaseFTSVectorSearchTool(...)  # works

Defensive patterns

Strategy: validation

Validate before calling

def couchbase_available() -> bool:
    try:
        import couchbase  # noqa: F401
        return True
    except ImportError:
        return False

if not couchbase_available():
    raise RuntimeError("Install couchbase before using CouchbaseFTSVectorSearchTool")

Try / catch

try:
    tool = CouchbaseFTSVectorSearchTool(...)
except ImportError as e:
    if "couchbase" in str(e):
        subprocess.run(["uv", "add", "couchbase"], check=True)
        tool = CouchbaseFTSVectorSearchTool(...)
    else:
        raise

Prevention

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.

When it happens

Trigger: 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.

Common situations: 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.

Related errors

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