locustio/locust · error · ValueError

'collection_name' must be provided for QdrantUser

Error message

'collection_name' must be provided for QdrantUser

What it means

QdrantUser requires a target collection name to operate on. The constructor checks `self.collection_name` immediately after delegating to super().__init__, and raises ValueError when it is None because the client cannot be constructed without a collection.

Source

Thrown at locust/contrib/qdrant.py:171

    **collection_kwargs
        Additional keyword arguments forwarded to ``create_collection``.
    """

    abstract = True

    url: str = "http://localhost:6333"
    api_key: str | None = None
    collection_name: str | None = None
    timeout: int = 60
    vectors_config: VectorParams | None = None
    client_kwargs: dict | None = None
    collection_kwargs: dict | None = None

    def __init__(self, environment):
        super().__init__(environment)

        if self.collection_name is None:
            raise ValueError("'collection_name' must be provided for QdrantUser")

        self.client_type = "qdrant"
        self.client = QdrantLocustClient(
            url=self.url,
            api_key=self.api_key,
            collection_name=self.collection_name,
            timeout=self.timeout,
            **(self.client_kwargs or {}),
        )
        if self.vectors_config is not None:
            self.client.create_collection(vectors_config=self.vectors_config, **(self.collection_kwargs or {}))

    @staticmethod
    def _fire_event(request_type: str, name: str, result: dict[str, Any]):
        """Emit a Locust request event from a Qdrant client result dict."""
        response_time = int(result.get("response_time", 0))
        events.request.fire(
            request_type=f"{request_type}",

View on GitHub (pinned to f391a716e1)

Solutions

  1. Add `collection_name = "your-collection"` as a class attribute on your QdrantUser subclass
  2. If loading from config/env, assign the value in the class body or before Environment creates user instances
  3. Verify the attribute is not accidentally overridden to None in a subclass

Example fix

// before
class MyUser(QdrantUser):
    url = "http://localhost:6333"
// after
class MyUser(QdrantUser):
    url = "http://localhost:6333"
    collection_name = "my_collection"
Defensive patterns

Strategy: validation

Validate before calling

class MyUser(QdrantUser):
    collection_name = os.environ["QDRANT_COLLECTION"]

assert MyUser.collection_name, "collection_name must be set"

Type guard

def has_collection(user) -> bool:
    return getattr(user, "collection_name", None) is not None

Try / catch

try:
    user = MyUser(environment)
except ValueError as e:
    if "collection_name" in str(e):
        raise RuntimeError("Set collection_name on your QdrantUser subclass") from e
    raise

Prevention

When it happens

Trigger: Defining a QdrantUser subclass without setting `collection_name` as a class attribute; setting it to None explicitly; instantiating QdrantUser programmatically without the attribute.

Common situations: Copy-pasting a QdrantUser example and forgetting to fill in the collection name; renaming config keys so `collection_name` no longer maps to the class attribute; building users dynamically from config where the key is missing.

Understand the failure class

Background: "X is required", "must be set", "cannot be empty": the missing-required-config error family, from Vertex AI project/location to WeChat keys — this error's family across 18 libraries.

Related errors

AI-assisted analysis of locustio/locust@f391a716e1 (2026-08-29). Data as JSON: /api/errors/3a03d28e5588fb34. Report an issue: GitHub.