crewAIInc/crewAI · error · ValueError

Bucket {self.bucket_name} does not exist. Please create the

Error message

Bucket {self.bucket_name} does not exist.  Please create the bucket before searching.

What it means

CouchbaseFTSVectorSearchTool raises this ValueError during __init__ after it successfully connects and authenticates to the Couchbase cluster, but before searching, when _check_bucket_exists() reports the configured bucket_name is not present on the cluster. The tool needs the bucket (plus its scope/collection and a search index) to run vector queries. It means your connection string and credentials are fine; the bucket itself is the problem.

Source

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

        Raises:
            ValueError: If required parameters are missing, the Couchbase cluster
                        cannot be reached, or the specified bucket, scope,
                        collection, or index does not exist.
        """
        super().__init__(**kwargs)
        if COUCHBASE_AVAILABLE:
            try:
                self._bucket = self.cluster.bucket(self.bucket_name)
                self._scope = self._bucket.scope(self.scope_name)
                self._collection = self._scope.collection(self.collection_name)
            except Exception as e:
                raise ValueError(
                    "Error connecting to couchbase. "
                    "Please check the connection and credentials"
                ) from e

            if not self._check_bucket_exists():
                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(

View on GitHub (pinned to 754d7323be)

Solutions

1. Open the Couchbase UI (or Capella console) for the cluster you are connecting to and confirm the bucket exists; create it or load the travel-sample dataset if that is what you intended.
2. Double-check the exact bucket_name string (case-sensitive) passed to CouchbaseFTSVectorSearchTool against the cluster.
3. Verify your connection string / credentials point at the cluster that actually holds the bucket (dev vs prod vs Capella project).
4. Create the bucket programmatically: cluster.bucket_manager().create_bucket(CreateBucketSettings(name="...", ram_quota_mb=100)) before instantiating the tool.

Example fix

# before
tool = CouchbaseFTSVectorSearchTool(
    bucket_name="Travel-Sample",  # wrong case; bucket is 'travel-sample'
    ...
)

# after
tool = CouchbaseFTSVectorSearchTool(
    bucket_name="travel-sample",
    ...
)

from couchbase.cluster import Cluster

def bucket_exists(cluster: "Cluster", bucket_name: str) -> bool:
    try:
        return any(b.name == bucket_name for b in cluster.buckets().get_all())
    except Exception:
        return False

# before constructing the tool:
assert bucket_exists(cluster, "travel-sample"), "create the bucket first"

try:
    tool = CouchbaseFTSVectorSearchTool(bucket_name=b, ...)
except ValueError as e:
    if "does not exist" in str(e):
        # create bucket or fix name, then retry construction
        ...
    raise

When it happens

Trigger: Instantiating CouchbaseFTSVectorSearchTool(bucket_name="travel-sample", ...) against a cluster where that bucket was dropped or never created, or where the bucket name has a typo/case mismatch. Also happens when connecting to the wrong cluster/environment (e.g. production connection string in a dev run) or when using Capella with a bucket that exists in another project.

Common situations: Typo in bucket_name; bucket deleted by a teammate or cleanup job; connecting to the wrong Capella project/cluster via CREWAI env vars or connection string; assuming the travel-sample bucket is loaded when the cluster is fresh.

Related errors

• Project name cannot be empty
• Project name '{name}' produces invalid folder name '{folder_
• No deployable project files were found.
• Deployment status response did not include a uuid
• Database URI is required for MySQL loader

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