chroma-core/chroma · error · ValueError

limit can only be specified when a where or where_document c

Error message

limit can only be specified when a where or where_document clause is provided

What it means

A delete limit only makes sense as a cap on a filtered match set. SegmentAPI rejects limit when the delete is id-based only: if limit is not None while both where and where_document are None, it raises ValueError('limit can only be specified when a where or where_document clause is provided') — with explicit ids the deletion set is already fully determined.

Source

Thrown at chromadb/api/segment.py:809

            where=where,
            where_document=where_document,
        )

        self._manager.hint_use_collection(collection_id, t.Operation.DELETE)

        if (where or where_document) or not ids:
            ids_to_delete = self._executor.get(
                GetPlan(scan, Filter(ids, where, where_document))
            )["ids"]
        else:
            ids_to_delete = ids

        # Apply limit if specified (validated upstream, but enforce defensively)
        if limit is not None:
            if not isinstance(limit, int) or isinstance(limit, bool) or limit < 0:
                raise ValueError("limit must be a non-negative integer")
            if where is None and where_document is None:
                raise ValueError(
                    "limit can only be specified when a where or where_document clause is provided"
                )
            ids_to_delete = ids_to_delete[:limit]

        if len(ids_to_delete) == 0:
            return DeleteResult(deleted=0)

        records_to_submit = list(
            _records(operation=t.Operation.DELETE, ids=ids_to_delete)
        )
        self._validate_embedding_record_set(scan.collection, records_to_submit)
        self._producer.submit_embeddings(collection_id, records_to_submit)

        deleted_count = len(ids_to_delete)

        self._product_telemetry_client.capture(
            CollectionDeleteEvent(
                collection_uuid=str(collection_id), delete_amount=deleted_count

View on GitHub (pinned to aecdd12c8a)

Solutions

Drop the limit for id-based deletes and slice the ids yourself: coll.delete(ids=ids[:5])
Build kwargs conditionally so limit is only included when where or where_document is set

Example fix

// before
coll.delete(ids=batch, limit=5)  # ValueError

// after
coll.delete(ids=batch[:5])

Defensive patterns

Strategy: validation

Validate before calling

def delete_limited(coll, ids=None, where=None, where_document=None, limit=None):
    if limit is not None and where is None and where_document is None:
        ids = (ids or [])[:limit]  # apply cap client-side instead
        limit = None
    return coll.delete(ids=ids, where=where, where_document=where_document, limit=limit)

Prevention

Only include limit in kwargs when a where/where_document clause is present
For id-based deletes, slice the ids list yourself
Keep one shared helper for delete() so the combination rules live in one place

When it happens

Trigger: coll.delete(ids=['a','b'], limit=5) — any delete that passes ids and a non-None limit but no where/where_document filter.

Common situations: A generic wrapper that always forwards a limit kwarg to delete(); reusing one kwargs dict for both filtered and id-based paths; porting code from APIs where limit truncated id lists.

Related errors

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