microsoft/semantic-kernel · error · VectorStoreInitializationException

Failed to create Azure CosmosDB for MongoDB settings.

Error message

Failed to create Azure CosmosDB for MongoDB settings.

What it means

CosmosMongoCollection builds a CosmosMongoSettings object from constructor args and environment variables. If that pydantic settings validation fails (typically a missing required connection string or malformed value), the library wraps the ValidationError in a VectorStoreInitializationException. This fires during collection construction, before any network call.

Source

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

                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,
                env_file_encoding=env_file_encoding,
                connection_string=connection_string,
                database_name=database_name,
            )
        except ValidationError as exc:
            raise VectorStoreInitializationException("Failed to create Azure CosmosDB for MongoDB settings.") from exc

        mongo_client = AsyncMongoClient(
            settings.connection_string.get_secret_value(),
            driver=DriverInfo(SEMANTIC_KERNEL_USER_AGENT, metadata.version("semantic-kernel")),
        )

        super().__init__(
            record_type=record_type,
            definition=definition,
            collection_name=collection_name,
            mongo_client=mongo_client,
            managed_client=managed_client,
            database_name=settings.database_name,
            embedding_generator=embedding_generator,
        )

    @override
    async def ensure_collection_exists(self, **kwargs) -> None:

View on GitHub (pinned to c028a0c7dc)

Solutions

1. Set the required connection string environment variable (check CosmosMongoSettings for the exact name) and any database_name env var.
2. Pass connection_string=... directly to the constructor.
3. If using a .env file, pass env_file_path and env_file_encoding, or load it via python-dotenv before construction.
4. Supply a pre-built mongo_client to bypass settings validation entirely.

Example fix

// before
export COSMOS_DB_MONGODB_CONNECTION_STRING=""
// after
export COSMOS_DB_MONGODB_CONNECTION_STRING="mongodb+srv://user:pass@account.mongo.cosmos.azure.com/?retryWrites=true&w=majority"

import os
required = ["COSMOS_DB_MONGODB_CONNECTION_STRING"]  # confirm exact name in CosmosMongoSettings
missing = [v for v in required if not os.getenv(v)]
if missing:
    raise RuntimeError(f"Missing env vars: {missing}")

try:
    collection = CosmosMongoCollection(...)
except VectorStoreInitializationException as e:
    cause = e.__cause__
    if isinstance(cause, ValidationError):
        # missing/malformed settings -> fix env or pass connection_string
        ...

When it happens

Trigger: Raised in CosmosMongoCollection.__init__ when CosmosMongoSettings(...) raises ValidationError. Triggered when no mongo_client is supplied and the environment lacks the required connection string (e.g. COSMOS_DB_MONGODB_CONNECTION_STRING), or when env vars are malformed. The same path is hit in CosmosMongoStore (error 1248).

Common situations: Missing environment variable for the connection string in local dev / CI. Wrong env var name after an SDK rename. A connection string that fails URL/format validation. Forgetting to load a .env file (env_file_path not set).

Related errors

• The collection name is required, can be passed directly or t
• Failed to validate Azure Cosmos DB NoSQL settings.
• The name of the Azure Cosmos DB NoSQL database is missing.
• Database '{self.database_name}' does not exist.
• Distance function '{field.distance_function}' is not support

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