microsoft/autogen · error · RuntimeError

Failed to initialize ChromaDB

Error message

Failed to initialize ChromaDB

What it means

Raised by ChromaDBVectorMemory.add when the internal _collection is still None after _ensure_initialized(). It signals that lazy initialization either never ran or failed without raising, so no collection handle exists to write to. In practice it means the memory was closed, reset, or failed to connect to the ChromaDB client.

Source

Thrown at python/packages/autogen-ext/src/autogen_ext/memory/chromadb/_chromadb.py:338

        query_text = last_message.content if isinstance(last_message.content, str) else str(last_message)

        # Query memory and get results
        query_results = await self.query(query_text)

        if query_results.results:
            # Format results for context
            memory_strings = [f"{i}. {str(memory.content)}" for i, memory in enumerate(query_results.results, 1)]
            memory_context = "\nRelevant memory content:\n" + "\n".join(memory_strings)

            # Add to context
            await model_context.add_message(SystemMessage(content=memory_context))

        return UpdateContextResult(memories=query_results)

    async def add(self, content: MemoryContent, cancellation_token: CancellationToken | None = None) -> None:
        self._ensure_initialized()
        if self._collection is None:
            raise RuntimeError("Failed to initialize ChromaDB")

        try:
            # Extract text from content
            text = self._extract_text(content)

            # Use metadata directly from content
            metadata_dict = content.metadata or {}
            metadata_dict["mime_type"] = str(content.mime_type)

            # Add to ChromaDB
            self._collection.add(documents=[text], metadatas=[metadata_dict], ids=[str(uuid.uuid4())])

        except Exception as e:
            logger.error(f"Failed to add content to ChromaDB: {e}")
            raise

    async def query(
        self,

View on GitHub (pinned to 027ecf0a37)

Solutions

1. Do not call add() after close()/reset(); create a fresh ChromaDBVectorMemory instance for the next session.
2. Ensure construction arguments (client_type, path, collection settings) are valid so first use initializes the collection successfully.
3. If a background task adds memories, await its cancellation and join before closing the memory in shutdown.

Example fix

# before
await memory.close()
await memory.add(content)  # RuntimeError

# after
await memory.close()
memory = ChromaDBVectorMemory(config=ChromaDBVectorMemoryConfig(collection_name='memos'))
await memory.add(content)

def memory_ready(memory) -> bool:
    return getattr(memory, '_collection', None) is not None or memory._client is not None and False

try:
    await memory.add(content)
except RuntimeError as e:
    if 'Failed to initialize' in str(e):
        memory = await rebuild_memory()  # fresh instance, retry once
        await memory.add(content)
    else:
        raise

When it happens

Trigger: Calling add() after close() (which sets _collection = None); calling add() after reset(); _ensure_initialized failing silently (e.g. PersistentClient path with a bad directory or client error swallowed elsewhere); calling add() on a memory instance deserialized/reconstructed without initialization.

Common situations: Reusing a memory object across agent runs after an explicit close in cleanup code; telemetry/shutdown hooks closing memory while background tasks still add; PersistentClient failing due to permissions or a locked SQLite directory so the collection is never created.

Related errors

• JSON content must be a dict
• Image content cannot be converted to text
• Unsupported content type: {mime_type}
• Reset not allowed. Set allow_reset=True in config to enable.
• Kernel is not running

AI-assisted analysis of microsoft/autogen@027ecf0a37 (2026-08-15). Data as JSON: /api/errors/5798b262187daa84. Report an issue: GitHub.