microsoft/semantic-kernel · error · VectorStoreInitializationException

Failed to validate Azure Cosmos DB NoSQL settings.

Error message

Failed to validate Azure Cosmos DB NoSQL settings.

What it means

CosmosNoSqlBase.__init__ constructs CosmosNoSqlSettings from url/key/database_name and env files. If pydantic validation fails (missing/malformed URL, conflicting key + credential, bad env), it raises VectorStoreInitializationException. This guards all NoSQL collection/store construction.

Source

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

            cosmos_client (CosmosClient): The custom Azure Cosmos DB NoSQL client whose lifetime is managed by the user.
                                          Defaults to None.
            create_database (bool): If True, the database will be created if it does not exist.
                                    Defaults to False.
            env_file_path (str): The path to the .env file. Defaults to None.
            env_file_encoding (str): The encoding of the .env file. Defaults to None.
            credential: The credential to use for authentication to Azure Cosmos DB NoSQL.
            kwargs: Additional keyword arguments.
        """
        try:
            cosmos_db_nosql_settings = CosmosNoSqlSettings(
                url=url,
                key=key,
                database_name=database_name,
                env_file_path=env_file_path,
                env_file_encoding=env_file_encoding,
            )
        except ValidationError as e:
            raise VectorStoreInitializationException("Failed to validate Azure Cosmos DB NoSQL settings.") from e

        if cosmos_db_nosql_settings.database_name is None:
            raise VectorStoreInitializationException("The name of the Azure Cosmos DB NoSQL database is missing.")

        if cosmos_client is None:
            if cosmos_db_nosql_settings.key is not None:
                cosmos_client = CosmosClient(
                    str(cosmos_db_nosql_settings.url), credential=cosmos_db_nosql_settings.key.get_secret_value()
                )
            else:
                if credential is None:
                    raise VectorStoreInitializationException(
                        "The 'credential' parameter is required for authentication."
                    )
                cosmos_client = CosmosClient(str(cosmos_db_nosql_settings.url), credential=credential)

        super().__init__(
            cosmos_client=cosmos_client,

View on GitHub (pinned to c028a0c7dc)

Solutions

1. Provide url= explicitly (a valid https URL) or set the corresponding environment variable.
2. If using a key, also set the key env var; if using Entra ID, pass credential= and omit key.
3. Pass a pre-built cosmos_client to bypass settings construction.
4. Check env var names against CosmosNoSqlSettings field aliases.

Example fix

// before
client = CosmosNoSqlCollection(record_type=MyModel, collection_name="items")
// after
client = CosmosNoSqlCollection(record_type=MyModel, collection_name="items", url="https://myaccount.documents.azure.com:443/", key="<primary-key>")

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

try:
    base = CosmosNoSqlBase(...)
except VectorStoreInitializationException as e:
    if isinstance(e.__cause__, ValidationError):
        # show field-level errors from e.__cause__.errors()
        ...

When it happens

Trigger: Raised in CosmosNoSqlBase.__init__ when CosmosNoSqlSettings(...) raises ValidationError. Triggered when the Cosmos DB account URL is missing or not a valid HttpUrl, when env_file_path is unreadable, or when a combination of url/key/credential fails settings-level constraints.

Common situations: Missing COSMOS_DB_NOSQL_URL environment variable in CI/local dev. URL without https:// scheme. Conflicting key vs credential configuration. Wrong env var alias after an SDK rename.

Related errors

• Failed to create Azure CosmosDB for MongoDB settings.
• The collection name is required, can be passed directly or t
• The name of the Azure Cosmos DB NoSQL database is missing.
• The 'credential' parameter is required for authentication.
• Database '{self.database_name}' does not exist.

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