microsoft/semantic-kernel · error · VectorStoreInitializationException

The 'credential' parameter is required for authentication.

Error message

The 'credential' parameter is required for authentication.

What it means

When constructing a CosmosClient without a key, the connector falls back to token-based authentication. If neither a key nor a credential object is available, it cannot authenticate and raises VectorStoreInitializationException. This is an auth-config guard at construction time.

Source

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

                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,
            **kwargs,
        )

    async def _does_database_exist(self) -> bool:
        """Checks if the database exists."""
        try:
            await self.cosmos_client.get_database_client(self.database_name).read()
            return True
        except CosmosResourceNotFoundError:

View on GitHub (pinned to c028a0c7dc)

Solutions

1. Pass a credential such as credential=DefaultAzureCredential() (from azure.identity.aio) when not using a key.
2. Or supply the account key via key= or the key env var.
3. Or pass a pre-configured cosmos_client that already has credentials resolved.

Example fix

// before
client = CosmosNoSqlCollection(..., url=url)  # no key, no credential
// after
from azure.identity.aio import DefaultAzureCredential
client = CosmosNoSqlCollection(..., url=url, credential=DefaultAzureCredential())

if not key and not os.getenv("COSMOS_DB_NOSQL_KEY") and credential is None:
    raise ValueError("Either a key or a credential must be supplied for CosmosNoSql auth")

When it happens

Trigger: Raised in CosmosNoSqlBase.__init__ when cosmos_client is None, cosmos_db_nosql_settings.key is None, and the caller passed credential=None. Triggered when you rely on Entra ID but forget to supply an AsyncTokenCredential (e.g. DefaultAzureCredential).

Common situations: Forgetting to pass credential=DefaultAzureCredential() when not using a key. Assuming Managed Identity is picked up automatically without wiring the credential. Confusion between key-based and Entra ID auth paths.

Understand the failure class

• Authentication and authorization failures — expired tokens, bad credentials, and missing scopes.

Related errors

• The collection name is required, can be passed directly or t
• Failed to create Azure CosmosDB for MongoDB settings.
• Failed to validate Azure Cosmos DB NoSQL settings.
• The name of the Azure Cosmos DB NoSQL database is missing.
• Failed to check if database '{self.database_name}' exists, w

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