chroma-core/chroma · error · ValueError

At least one of ids, where, or where_document must be provid

Error message

At least one of ids, where, or where_document must be provided

What it means

`_validate_and_prepare_delete_request` requires at least one selector for a delete. Deleting everything implicitly is dangerous and not supported, so `collection.delete()` with ids, where, and where_document all None is rejected.

Source

Thrown at chromadb/api/models/CollectionCommon.py:473

        return UpsertRequest(
            ids=upsert_records["ids"],
            metadatas=upsert_metadatas,
            embeddings=upsert_embeddings,
            documents=upsert_records["documents"],
            uris=upsert_records["uris"],
        )

    @validation_context("delete")
    def _validate_and_prepare_delete_request(
        self,
        ids: Optional[IDs],
        where: Optional[Where],
        where_document: Optional[WhereDocument],
        limit: Optional[int] = None,
    ) -> DeleteRequest:
        if ids is None and where is None and where_document is None:
            raise ValueError(
                "At least one of ids, where, or where_document must be provided"
            )

        if limit is not None:
            if not isinstance(limit, int) or isinstance(limit, bool):
                raise TypeError("limit must be a non-negative integer")
            if limit < 0:
                raise ValueError("limit must be a non-negative integer")

        if limit is not None and where is None and where_document is None:
            raise ValueError(
                "limit can only be specified when a where or where_document clause is provided"
            )

        # Unpack
        if ids is not None:
            request_ids = cast(IDs, maybe_cast_one_to_many(ids))
        else:

View on GitHub (pinned to aecdd12c8a)

Solutions

Pass at least one selector: ids, where, or where_document
If delete-all is intended, list the IDs first (`collection.get(include=[])`) and delete by ids
Guard the call: only invoke delete when at least one filter is non-None

Example fix

# before
collection.delete(ids=ids, where=where)  # both None

# after
if ids is None and where is None and where_document is None:
    raise ValueError("refusing to delete without a selector")
collection.delete(ids=ids, where=where, where_document=where_document)

Defensive patterns

Strategy: validation

Validate before calling

if ids is None and where is None and where_document is None:
    raise ValueError("delete needs at least one of ids/where/where_document")
collection.delete(ids=ids, where=where, where_document=where_document)

Prevention

Build optional-filter objects and skip the delete call entirely when all are unset
Treat delete-all as an explicit ids list obtained from get(), never as a no-filter delete
Add a lint/unit check that no call site invokes delete() with zero selectors

When it happens

Trigger: `collection.delete()` with no arguments, or `collection.delete(ids=None, where=None, where_document=None)` (e.g. all filter variables end up None at runtime).

Common situations: Building filters dynamically where every condition is optional and all end up unset; porting code from another vector DB that allows an unfiltered delete-all.

Related errors

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