microsoft/semantic-kernel · error · VectorStoreOperationException

Failed to check if database '{self.database_name}' exists, w

Error message

Failed to check if database '{self.database_name}' exists, with message {e}

What it means

CosmosNoSqlStore._does_database_exist calls read() on the database client inside a try; a CosmosResourceNotFoundError maps to 'does not exist' (returns False), but any other exception is wrapped as VectorStoreOperationException. This is a runtime existence probe, so failures are typically transport/auth/permission related.

Source

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

                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:
            return False
        except Exception as e:
            raise VectorStoreOperationException(
                f"Failed to check if database '{self.database_name}' exists, with message {e}"
            ) from e

    async def _get_database_proxy(self, **kwargs) -> DatabaseProxy:
        """Gets the database proxy."""
        try:
            if await self._does_database_exist():
                return self.cosmos_client.get_database_client(self.database_name)

            if self.create_database:
                return await self.cosmos_client.create_database(self.database_name, **kwargs)
            raise VectorStoreOperationException(f"Database '{self.database_name}' does not exist.")
        except Exception as e:
            raise VectorStoreOperationException(f"Failed to get database proxy for '{id}'.") from e

    async def _get_container_proxy(self, container_name: str, **kwargs) -> ContainerProxy:
        """Gets the container proxy."""
        try:

View on GitHub (pinned to c028a0c7dc)

Solutions

1. Read exc.__cause__ for the HTTP status: 401/403 -> fix key/credential; 429 -> back off / raise RU; network -> check firewall and connectivity.
2. Ensure the client host can reach the Cosmos account endpoint.
3. Retry transient failures with exponential backoff.
4. Verify the key/credential has access to the account.

try:
    exists = await store._does_database_exist()
except VectorStoreOperationException as e:
    cause = e.__cause__
    # 401/403 -> auth; 429 -> throttle/backoff; network -> connectivity

When it happens

Trigger: Raised in _does_database_exist when cosmos_client.get_database_client(name).read() raises anything other than CosmosResourceNotFoundError. Causes include 401/403 (bad key or credential), throttling (429), network errors, firewall blocking the account, or a transient service error.

Common situations: Expired or rotated account key. Entra ID token expiry. Cosmos DB firewall / virtual network blocking the client. Throttling under high RU usage. Transient Azure service incidents.

Related errors

• Failed to search the collection.
• Failed to get database proxy for '{id}'.
• Failed to get container proxy for '{container_name}'.
• The 'credential' parameter is required for authentication.
• Failed to delete item(s).

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