microsoft/semantic-kernel · error · VectorStoreOperationException

Failed to create container.

Error message

Failed to create container.

What it means

Raised when database_proxy.create_container_if_not_exists fails with a CosmosHttpResponseError during collection creation. The original HTTP error (with status code and message) is chained. This is a VectorStoreOperationException indicating the container/indexing/vector-embedding policy could not be applied server-side.

Source

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

        return deserialized_records

    @override
    async def ensure_collection_exists(self, **kwargs) -> None:
        indexing_policy = kwargs.pop("indexing_policy", _create_default_indexing_policy_nosql(self.definition))
        vector_embedding_policy = kwargs.pop(
            "vector_embedding_policy", _create_default_vector_embedding_policy(self.definition)
        )
        database_proxy = await self._get_database_proxy(**kwargs)
        try:
            await database_proxy.create_container_if_not_exists(
                id=self.collection_name,
                partition_key=self.partition_key,
                indexing_policy=indexing_policy,
                vector_embedding_policy=vector_embedding_policy,
                **kwargs,
            )
        except CosmosHttpResponseError as e:
            raise VectorStoreOperationException("Failed to create container.") from e

    @override
    async def collection_exists(self, **kwargs) -> bool:
        container_proxy = await self._get_container_proxy(self.collection_name, **kwargs)
        try:
            await container_proxy.read(**kwargs)
            return True
        except CosmosHttpResponseError:
            return False

    @override
    async def ensure_collection_deleted(self, **kwargs) -> None:
        database_proxy = await self._get_database_proxy(**kwargs)
        try:
            await database_proxy.delete_container(self.collection_name)
        except Exception as e:
            raise VectorStoreOperationException("Container could not be deleted.") from e

View on GitHub (pinned to c028a0c7dc)

Solutions

1. Inspect exc.__cause__ (the CosmosHttpResponseError) for the exact HTTP status and message — e.g. 400 bad request pinpoints the policy problem.
2. Correct the container name (alphanumeric, no reserved chars) and validate the indexing + vector embedding policy fields/dimensions/distance functions against Cosmos limits.
3. Confirm the configured identity/key has container-create permission on the database.

Example fix

// before
await store.create_collection()  # raises 'Failed to create container.'
// after
try:
    await store.create_collection()
except VectorStoreOperationException as e:
    print(e.__cause__)  # CosmosHttpResponseError with status + reason

from semantic_kernel.exceptions import VectorStoreOperationException

try:
    await store.create_collection()
except VectorStoreOperationException as e:
    cause = e.__cause__
    status = getattr(cause, "status_code", None)
    raise RuntimeError(f"Container create failed (HTTP {status}): {cause}") from e

When it happens

Trigger: Calling create_collection / ensure_collection_exists and the Cosmos service rejects the create request: invalid container name characters, a partition key definition that conflicts, an indexing/vector policy that violates limits (e.g. too many vector fields, unsupported vector index type), or insufficient permissions.

Common situations: Naming the collection with an illegal character, declaring a vector embedding policy whose dimensions or distance function are unsupported for the chosen vector index type (e.g. diskANN vs flat), or the principal lacking 'create container' RBAC.

Related errors

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

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