mem0ai/mem0 · error · ValueError

'cluster_url' must be provided.

Error message

'cluster_url' must be provided.

What it means

WeaviateConfig's `before` validator requires a truthy 'cluster_url' value; the field is Optional[str] with default None, so omitting it, passing None, or passing an empty string triggers this ValueError at config construction. This mirrors the weaviate-client requirement for an explicit endpoint (Weaviate has no discovery mechanism).

Source

Thrown at mem0/configs/vector_stores/weaviate.py:23

class WeaviateConfig(BaseModel):
    from weaviate import WeaviateClient

    WeaviateClient: ClassVar[type] = WeaviateClient

    collection_name: str = Field("mem0", description="Name of the collection")
    embedding_model_dims: int = Field(1536, description="Dimensions of the embedding model")
    cluster_url: Optional[str] = Field(None, description="URL for Weaviate server")
    auth_client_secret: Optional[str] = Field(None, description="API key for Weaviate authentication")
    additional_headers: Optional[Dict[str, str]] = Field(None, description="Additional headers for requests")

    @model_validator(mode="before")
    @classmethod
    def check_connection_params(cls, values: Dict[str, Any]) -> Dict[str, Any]:
        cluster_url = values.get("cluster_url")

        if not cluster_url:
            raise ValueError("'cluster_url' must be provided.")

        return values

    @model_validator(mode="before")
    @classmethod
    def validate_extra_fields(cls, values: Dict[str, Any]) -> Dict[str, Any]:
        allowed_fields = set(cls.model_fields.keys())
        input_fields = set(values.keys())
        extra_fields = input_fields - allowed_fields

        if extra_fields:
            raise ValueError(
                f"Extra fields not allowed: {', '.join(extra_fields)}. Please input only the following fields: {', '.join(allowed_fields)}"
            )

        return values

    model_config = ConfigDict(arbitrary_types_allowed=True)

View on GitHub (pinned to 001c235229)

Solutions

  1. Pass cluster_url explicitly: config={'cluster_url': 'https://my-cluster.weaviate.network'} or 'http://localhost:8080' for local Weaviate
  2. Load it from your environment when building the config: cluster_url=os.environ['WEAVIATE_URL']
  3. Double-check the key is exactly 'cluster_url' — 'url'/'host' are rejected

Example fix

# before
config = {}

# after
config = {"cluster_url": "http://localhost:8080", "auth_client_secret": None}
Defensive patterns

Strategy: validation

Validate before calling

if not cfg.get("cluster_url"):
    raise ConfigError("weaviate config requires cluster_url (e.g. http://localhost:8080)")

Try / catch

try:
    memory = Memory(config=full_config)
except ValueError as e:
    if "cluster_url" in str(e):
        cfg["cluster_url"] = os.environ["WEAVIATE_URL"]
        memory = Memory(config=full_config)
    else:
        raise

Prevention

When it happens

Trigger: Memory(vector_store={'provider': 'weaviate'}) with no config.cluster_url; passing cluster_url='' or None; passing the URL under a different key (url, host) which then also trips the extra-fields validator.

Common situations: Assuming WEAVIATE_URL is read from the environment (this config requires it explicitly); embedding Weaviate locally (embedded options) and not realizing this config still demands a URL; URL kept in a .env that was never loaded.

Related errors

AI-assisted analysis of mem0ai/mem0@001c235229 (2026-08-15). Data as JSON: /api/errors/82fc621c0da9fe71. Report an issue: GitHub.