microsoft/semantic-kernel · error · VectorStoreInitializationException

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

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.

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.

Appendix: 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)