chroma-core/chroma · error · NotImplementedError

Collection forking is not implemented for Local Chroma

Error message

Collection forking is not implemented for Local Chroma

What it means

RustBindingsAPI._fork (chromadb/api/rust.py:362) is an intentional stub. Collection forking (Collection.fork(new_name)) is implemented only by the Chroma server; the embedded Rust bindings backend (chromadb.RustClient or Settings(chroma_api_impl='chromadb.api.rust.RustBindingsAPI')) has no forking implementation, so every fork() call in that mode raises NotImplementedError.

Source

Thrown at chromadb/api/rust.py:362

        if new_configuration:
            new_configuration_json_str = update_collection_configuration_to_json_str(
                new_configuration
            )
        else:
            new_configuration_json_str = None
        self.bindings.update_collection(
            str(id), new_name, new_metadata, new_configuration_json_str
        )

    @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 Local Chroma"
        )

    @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 Local Chroma")

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

View on GitHub (pinned to aecdd12c8a)

Solutions

Connect with chromadb.HttpClient(host=..., port=...) to a running Chroma server (started via `chroma run`) - the server implements _fork
If you must stay embedded, emulate a fork: create a new collection and copy records with get() + add()
Feature-detect the backend before calling fork() and branch (skip, warn, or copy) when running embedded

Example fix

# before (embedded Rust client - raises NotImplementedError)
client = chromadb.RustClient(path='./data')
clone = client.get_collection('docs').fork('docs-copy')

# after (server client - supported)
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:
    """True when the client talks to a Chroma server (supports fork)."""
    return type(client._server).__module__.startswith('chromadb.api.fastapi')

Try / catch

try:
    clone = collection.fork('docs-copy')
except NotImplementedError:
    # embedded Rust backend: fall back to manual copy
    clone = client.create_collection('docs-copy')
    batch = collection.get(include=['embeddings', 'documents', 'metadatas'])
    clone.add(ids=batch['ids'], embeddings=batch['embeddings'],
              documents=batch['documents'], metadatas=batch['metadatas'])

Prevention

Decide deployment mode up front: any fork usage requires HttpClient against a running `chroma run` server
Wrap server-only features behind a thin capability layer that checks the backend once at startup
Keep embedded test suites limited to the API surface the embedded backend implements

When it happens

Trigger: client = chromadb.RustClient(path='./data'); client.get_collection('docs').fork('docs-v2'). Any sync Collection.fork or async AsyncCollection.fork call whose client routes to the Rust bindings API implementation.

Common situations: Writing forking code against a Chroma server then running the same script locally with the embedded Rust client; switching chroma_api_impl to the Rust implementation for speed; CI suites that use embedded clients to test server-only features.

Related errors

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