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

`limit` on delete only bounds a predicate-based delete. It has no meaning for delete-by-ids (ids are explicit and unordered), so passing limit together with ids but no where/where_document is rejected.

Source

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

        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:
            request_ids = None
        filters = FilterSet(where=where, where_document=where_document)

        # Validate
        if request_ids is not None:
            validate_ids(ids=request_ids)
        validate_filter_set(filter_set=filters)

        return DeleteRequest(
            ids=request_ids, where=where, where_document=where_document, limit=limit
        )

View on GitHub (pinned to aecdd12c8a)

Solutions

Remove the limit argument when deleting by ids
If you want to bound how many ids are deleted, slice the list yourself: `collection.delete(ids=ids[:100])`
If you want bounded predicate deletion, supply where or where_document alongside limit

Example fix

# before
collection.delete(ids=batch_ids, limit=100)  # ValueError

# after
collection.delete(ids=batch_ids[:100])

Defensive patterns

Strategy: validation

Validate before calling

if limit is not None and where is None and where_document is None:
    limit = None  # limit is meaningless for id-only deletes
collection.delete(ids=ids, where=where, where_document=where_document, limit=limit)

Prevention

Apply limit only on predicate deletes
Bound id-based deletes by slicing the ids list yourself
Keep delete kwargs construction explicit rather than reusing a shared dict

When it happens

Trigger: `collection.delete(ids=["a", "b"], limit=5)` — ids provided, where and where_document None.

Common situations: Reusing a kwargs dict built for a filtered delete and adding ids; assuming limit applies to batched id deletion.

Related errors

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