microsoft/semantic-kernel · error · VectorStoreInitializationException

The name of the Azure Cosmos DB NoSQL database is missing.

Error message

The name of the Azure Cosmos DB NoSQL database is missing.

What it means

After CosmosNoSqlSettings validates, the NoSQL base checks that database_name resolved to a non-None value. Cosmos requires a database name to operate, so an empty/None name is treated as a hard initialization failure distinct from generic settings validation.

Source

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

                                    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,
            database_name=cosmos_db_nosql_settings.database_name,
            cosmos_db_nosql_settings=cosmos_db_nosql_settings,
            create_database=create_database,

View on GitHub (pinned to c028a0c7dc)

Solutions

1. Pass database_name="mydb" to the constructor.
2. Set the database-name environment variable (see CosmosNoSqlSettings alias).
3. Add the variable to your .env / deployment config and reload.

Example fix

// before
store = CosmosNoSqlStore(url=url, key=key)
// after
store = CosmosNoSqlStore(url=url, key=key, database_name="mydb")

from semantic_kernel.connectors.azure_cosmos_db import CosmosNoSqlSettings
import os

db = database_name or os.getenv("COSMOS_DB_NOSQL_DATABASE")  # confirm alias
if not db:
    raise ValueError("database_name must be provided for CosmosNoSqlStore")

When it happens

Trigger: Raised in CosmosNoSqlBase.__init__ when cosmos_db_nosql_settings.database_name is None. Happens when no database_name was passed AND no corresponding environment variable is set, so the optional pydantic field stays None.

Common situations: Forgetting to pass database_name in local scripts. Missing the database-name env var in a container. Renaming the env var without updating deployment manifests.

Related errors

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

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