microsoft/semantic-kernel · error · VectorStoreInitializationException

The collection name is required, can be passed directly or t

Error message

The collection name is required, can be passed directly or through the data model.

What it means

CosmosMongoCollection requires a collection name either passed explicitly or derivable from the record type's data model (via a collection_name attribute or decorator metadata). When neither is present, the constructor cannot proceed and raises a VectorStoreInitializationException. This is an initialization-time guard, not a runtime failure.

Source

Thrown at python/semantic_kernel/connectors/azure_cosmos_db.py:319

            record_type: The type of the data model.
            definition: The model definition, optional.
            collection_name: The name of the collection, optional.
            embedding_generator: The embedding generator to use for generating embeddings.
            mongo_client: The MongoDB client for interacting with Azure CosmosDB for MongoDB,
                used for creating and deleting collections.
            connection_string: The connection string for MongoDB Atlas, optional.
            Can be read from environment variables.
            database_name: The name of the database, will be filled from the env when this is not set.
            connection_string: str | None = None,
            env_file_path: str | None = None,
            env_file_encoding: str | None = None
            **kwargs: Additional keyword arguments

        """
        if not collection_name:
            collection_name = _get_collection_name_from_model(record_type, definition)
        if not collection_name:
            raise VectorStoreInitializationException(
                "The collection name is required, can be passed directly or through the data model."
            )
        managed_client = not mongo_client
        if mongo_client:
            super().__init__(
                record_type=record_type,
                definition=definition,
                mongo_client=mongo_client,
                collection_name=collection_name,
                database_name=database_name or DEFAULT_DB_NAME,
                managed_client=managed_client,
                embedding_generator=embedding_generator,
            )
            return

        try:
            settings = CosmosMongoSettings(
                env_file_path=env_file_path,

View on GitHub (pinned to c028a0c7dc)

Solutions

Pass collection_name explicitly to the CosmosMongoCollection constructor.
Decorate the model with @vectorstoremodel(collection_name="my_collection") or set collection_name on the model.
Verify the record_type passed is the intended model class and not None or a base type.

Example fix

// before
collection = CosmosMongoCollection(record_type=MyModel)
// after
collection = CosmosMongoCollection(record_type=MyModel, collection_name="my_collection")

Defensive patterns

Strategy: validation

Validate before calling

from semantic_kernel.data.vector import _get_collection_name_from_model

resolved = collection_name or _get_collection_name_from_model(record_type, definition)
if not resolved:
    raise ValueError("collection_name must be passed or defined on the model")
collection = CosmosMongoCollection(record_type=record_type, collection_name=resolved)

Type guard

def has_collection_name(record_type: type, explicit: str | None) -> bool:
    return bool(explicit or getattr(record_type, "__collection_name__", None) or getattr(record_type, "collection_name", None))

Prevention

Always pass collection_name explicitly in production code.
Decorate models with @vectorstoremodel(collection_name=...) as a single source of truth.
Add an integration test that constructs each collection to catch missing names early.

When it happens

Trigger: Raised in CosmosMongoCollection.__init__ when collection_name is falsy AND _get_collection_name_from_model(record_type, definition) also returns falsy. Happens when you instantiate CosmosMongoCollection(record_type=MyModel) without collection_name and MyModel has no collection_name metadata (no @vectorstoremodel(collection_name=...) and no class attribute).

Common situations: Forgetting to pass collection_name when the model class wasn't decorated with a name. Renaming or removing the decorator metadata. Using a plain dataclass / pydantic model as record_type that was never registered as a vector store model.

Related errors

AI-assisted analysis of microsoft/semantic-kernel@c028a0c7dc (2026-08-13). Data as JSON: /api/errors/d6da711345169e02. Report an issue: GitHub.