chroma-core/chroma · error · ValueError

$knn limit must be positive, got {limit}

Error message

$knn limit must be positive, got {limit}

What it means

$knn's 'limit' must be >= 1; 0 and negatives raise ValueError. It controls how many nearest neighbors the scan fetches (default 16), so a non-positive value would produce an empty ranking by construction and is treated as a caller bug.

Source

Thrown at chromadb/execution/expression/operator.py:735

                query = normalized[0]

            else:
                raise TypeError(
                    f"$knn query must be a list, numpy array, or SparseVector dict, got {type(query).__name__}"
                )

            key = knn_data.get("key", "#embedding")
            if not isinstance(key, str):
                raise TypeError(f"$knn key must be a string, got {type(key).__name__}")

            limit = knn_data.get("limit", 16)
            if not isinstance(limit, int):
                raise TypeError(
                    f"$knn limit must be an integer, got {type(limit).__name__}"
                )
            if limit <= 0:
                raise ValueError(f"$knn limit must be positive, got {limit}")

            return_rank = knn_data.get("return_rank", False)
            if not isinstance(return_rank, bool):
                raise TypeError(
                    f"$knn return_rank must be a boolean, got {type(return_rank).__name__}"
                )

            return Knn(
                query=query,
                key=key,
                limit=limit,
                default=knn_data.get("default"),
                return_rank=return_rank,
            )

        elif op == "$sum":
            ranks_data = data["$sum"]
            if not isinstance(ranks_data, (list, tuple)):

View on GitHub (pinned to aecdd12c8a)

Solutions

1. Omit 'limit' (default 16) or pass a value >= 1.
2. Clamp computed values: max(1, top_k).
3. Return early for zero-result requests instead of building a $knn node.

Example fix

# before
Search(rank={'$knn': {'query': emb, 'limit': max(0, remaining)}})   # 0 -> ValueError

# after
Search(rank={'$knn': {'query': emb, 'limit': max(1, remaining)}})

top_k = knn_opts.get('limit', 16)
if top_k is not None and top_k < 1:
    raise ValueError(f'$knn limit must be >= 1, got {top_k}')

When it happens

Trigger: {'$knn': {'query': emb, 'limit': 0}}; {'limit': -5}; computed sizes like top_k = max(0, remaining) flooring to 0 on the last page.

Common situations: Dynamically sizing top_k from remaining result slots; users sending top_k=0 meaning 'no results'; defaults of 0 instead of omitting the key.

Related errors

• $knn requires 'query' field
• Expected dict with {TYPE_KEY}='{SPARSE_VECTOR_TYPE_VALUE}',
• $knn requires exactly one query embedding
• $knn limit must be an integer, got {type(limit).__name__}
• Limit offset must be non-negative, got {offset}

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