chroma-core/chroma · error · NotImplementedError

Collection forking is not implemented for SegmentAPI

Error message

Collection forking is not implemented for SegmentAPI

What it means

SegmentAPI._fork (chromadb/api/segment.py:453) is an intentional stub. Collection forking is implemented only by the Chroma server; SegmentAPI - the default backend for chromadb.PersistentClient and chromadb.EphemeralClient - cannot fork collections, so Collection.fork() raises NotImplementedError in all embedded modes.

Source

Thrown at chromadb/api/segment.py:453

            self._sysdb.update_collection(
                id, metadata=new_metadata, configuration=new_configuration
            )
        elif new_name:
            self._sysdb.update_collection(id, name=new_name)
        elif new_metadata:
            self._sysdb.update_collection(id, metadata=new_metadata)
        elif new_configuration:
            self._sysdb.update_collection(id, configuration=new_configuration)

    @override
    def _fork(
        self,
        collection_id: UUID,
        new_name: str,
        tenant: str = DEFAULT_TENANT,
        database: str = DEFAULT_DATABASE,
    ) -> CollectionModel:
        raise NotImplementedError(
            "Collection forking is not implemented for SegmentAPI"
        )

    @override
    def _fork_count(
        self,
        collection_id: UUID,
        tenant: str = DEFAULT_TENANT,
        database: str = DEFAULT_DATABASE,
    ) -> int:
        raise NotImplementedError("Fork count is not implemented for SegmentAPI")

    @override
    def _get_indexing_status(
        self,
        collection_id: UUID,
        tenant: str = DEFAULT_TENANT,
        database: str = DEFAULT_DATABASE,

View on GitHub (pinned to aecdd12c8a)

Solutions

  1. Connect to a Chroma server with chromadb.HttpClient (start one with `chroma run`) and fork there
  2. Emulate the fork embedded: create_collection + copy records via get()/add()
  3. Branch on backend type before calling fork()

Example fix

# before (raises NotImplementedError on PersistentClient/EphemeralClient)
client = chromadb.PersistentClient(path='./data')
clone = client.get_collection('docs').fork('docs-copy')

# after
client = chromadb.HttpClient(host='localhost', port=8000)
clone = client.get_collection('docs').fork('docs-copy')
Defensive patterns

Strategy: fallback

Validate before calling

def is_server_client(client) -> bool:
    """fork() exists only on the Chroma server (HttpClient)."""
    return type(client._server).__module__.startswith('chromadb.api.fastapi')

Try / catch

try:
    clone = collection.fork('docs-copy')
except NotImplementedError:
    # SegmentAPI (PersistentClient/EphemeralClient): manual copy fallback
    clone = client.create_collection('docs-copy')
    data = collection.get(include=['embeddings', 'documents', 'metadatas'])
    clone.add(ids=data['ids'], embeddings=data['embeddings'],
              documents=data['documents'], metadatas=data['metadatas'])

Prevention

When it happens

Trigger: client = chromadb.PersistentClient(path='./data'); client.get_collection('docs').fork('docs-copy') - same for EphemeralClient. Any fork() call that routes to SegmentAPI.

Common situations: Local development or notebook prototyping of code written for a Chroma server; test suites on ephemeral clients exercising fork-based snapshot flows.

Related errors

AI-assisted analysis of chroma-core/chroma@aecdd12c8a (2026-08-16). Data as JSON: /api/errors/2574eaca5d886645. Report an issue: GitHub.