What causes "Search is not implemented for SegmentAPI" in chroma-core/chroma?

Use collection.query(query_embeddings=..., n_results=...) instead of search() when running embedded

chroma-core/chroma · error · NotImplementedError

Search is not implemented for SegmentAPI

Error message

Search is not implemented for SegmentAPI

What it means

The multi-vector Search API (collection.search(...) with typed Search objects, per-search queries/filters and read levels) is declared on the shared API contract but is not implemented by the embedded SegmentAPI backend: _search raises NotImplementedError unconditionally. Embedded clients still support the classic collection.query(...) path, which is served by a different code path (the executor plan over the local segments).

Source

Thrown at chromadb/api/segment.py:484

    @override
    def _get_indexing_status(
        self,
        collection_id: UUID,
        tenant: str = DEFAULT_TENANT,
        database: str = DEFAULT_DATABASE,
    ) -> "IndexingStatus":
        raise NotImplementedError("Indexing status is not implemented for SegmentAPI")

    @override
    def _search(
        self,
        collection_id: UUID,
        searches: List[Search],
        tenant: str = DEFAULT_TENANT,
        database: str = DEFAULT_DATABASE,
        read_level: ReadLevel = ReadLevel.INDEX_AND_WAL,
    ) -> SearchResult:
        raise NotImplementedError("Search is not implemented for SegmentAPI")

    @trace_method("SegmentAPI.delete_collection", OpenTelemetryGranularity.OPERATION)
    @override
    @rate_limit
    def delete_collection(
        self,
        name: str,
        tenant: str = DEFAULT_TENANT,
        database: str = DEFAULT_DATABASE,
    ) -> None:
        existing = self._sysdb.get_collections(
            name=name, tenant=tenant, database=database
        )

        if existing:
            self._manager.delete_segments(existing[0].id)
            self._sysdb.delete_collection(
                existing[0].id, tenant=tenant, database=database

View on GitHub (pinned to aecdd12c8a)

Solutions

Use collection.query(query_embeddings=..., n_results=...) instead of search() when running embedded
Point the code at a Chroma server via chromadb.HttpClient, where search() is implemented
Add a capability branch: try/except NotImplementedError (or check chroma_api_impl) that falls back to query()

Example fix

// before
res = coll.search(queries=[...])  # NotImplementedError on PersistentClient

// after
res = coll.query(query_embeddings=[emb], n_results=10)

Defensive patterns

Strategy: fallback

Validate before calling

import chromadb

def supports_search(client: chromadb.ClientAPI) -> bool:
    impl = client.get_settings().chroma_api_impl
    return impl not in ('chromadb.api.segment.SegmentAPI', 'chromadb.api.rust.RustBindingsAPI')

Try / catch

try:
    res = coll.search(queries=queries)
except NotImplementedError:
    res = coll.query(query_embeddings=[q.query_embedding for q in queries], n_results=k)

Prevention

Prefer collection.query() for code that must run both embedded and against a server
Hide search()/query() behind one repository method so the backend switch is a single place
Document which endpoints of your app require the server backend

When it happens

Trigger: Calling collection.search(...) (which delegates to client._search(collection_id, searches, ...)) on an embedded client — chromadb.Client(), EphemeralClient, PersistentClient — or calling the internal _search directly.

Common situations: Adopting the newer search() API in code that must also run embedded in tests or notebooks; copy-pasting server-oriented example code; abstraction layers that pick between query() and search() without also switching the backend.

Related errors

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