microsoft/semantic-kernel · error · RuntimeError

Failed to get collection {self.collection_name}

Error message

Failed to get collection {self.collection_name}

What it means

Raised by ChromaCollection._get_collection() when the underlying chromadb client.get_collection() call throws any exception. This is a wrapper (RuntimeError) that masks the real chromadb cause via 'raise ... from e'. It fires whenever the named collection cannot be retrieved — most often because it does not exist on the client, or because the client connection (persistent path / host) is misconfigured.

Source

Thrown at python/semantic_kernel/connectors/chroma.py:127

                settings.is_persistent = True
                settings.persist_directory = persist_directory
            client = Client(settings)
        super().__init__(
            collection_name=collection_name,
            record_type=record_type,
            definition=definition,
            client=client,
            managed_client=managed_client,
            embedding_func=embedding_func,
            embedding_generator=embedding_generator,
            **kwargs,
        )

    def _get_collection(self) -> Collection:
        try:
            return self.client.get_collection(name=self.collection_name, embedding_function=self.embedding_func)
        except Exception as e:
            raise RuntimeError(f"Failed to get collection {self.collection_name}") from e

    @override
    async def collection_exists(self, **kwargs: Any) -> bool:
        """Check if the collection exists."""
        try:
            self.client.get_collection(name=self.collection_name, embedding_function=self.embedding_func)
            return True
        except Exception:
            return False

    @override
    async def ensure_collection_exists(self, **kwargs: Any) -> None:
        """Create the collection.

        Will create a metadata object with the hnsw arguments.
        By default only the distance function will be set based on the data model.
        To tweak the other hnsw parameters, pass them in the kwargs.

View on GitHub (pinned to c028a0c7dc)

Solutions

1. Call 'await collection.ensure_collection_exists()' before invoking any read/write/search operation on the collection.
2. Check the error's __cause__ (the original chromadb exception) to confirm whether the collection is truly missing vs. a connection/auth failure.
3. Verify self.collection_name matches the name used at creation and that the same ClientAPI instance (persist_directory / host / database) is used.

Example fix

// before
await collection.upsert(records)  # collection not created yet
// after
await collection.ensure_collection_exists()
await collection.upsert(records)

exists = await collection.collection_exists()
if not exists:
    await collection.ensure_collection_exists()

from semantic_kernel.exceptions.vector_store_exceptions import VectorStoreOperationException
try:
    col = collection._get_collection()
except RuntimeError as e:
    cause = e.__cause__
    # distinguish missing-collection vs connection failure via the chromadb cause

When it happens

Trigger: Calling any operation that internally calls _get_collection() (e.g. upsert, search, get) before ensure_collection_exists() has created the collection; or pointing the Chroma client at a persist_directory/tenant/database where the collection name is absent.

Common situations: Forgetting to call await collection.ensure_collection_exists() (or create_collection) before first read/write; switching persist_directory between runs; using a managed remote client where the collection lives in a different database/tenant; collection name typo or name derived from a model whose __semantic_kernel_collection_name__ differs from what was created.

Related errors

• Failed to delete collection {self.collection_name} with erro
• Index kind {vector_field.index_kind} is not supported.
• Distance function {vector_field.distance_function} is not su
• Chroma only supports one vector field, but {len(self.definit
• Vector field '{options.vector_property_name}' not found in t

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