chroma-core/chroma · error · TypeError

$knn limit must be an integer, got {type(limit).__name__}

Error message

$knn limit must be an integer, got {type(limit).__name__}

What it means

The optional 'limit' inside $knn - the number of neighbors fetched during the KNN scan, default 16 - must be a Python int. Strings like '16', floats like 16.0, and numpy ints raise TypeError. This is the KNN fetch size, distinct from the page-level Limit's 'limit' key.

Source

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

                    raise ValueError("$knn requires exactly one query embedding")

                # Validate the normalized version
                validate_embeddings(normalized)

                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,
            )

View on GitHub (pinned to aecdd12c8a)

Solutions

1. Cast at the boundary: {'limit': int(top_k)}.
2. Type top_k as int in your config/CLI parsing layer.
3. Leave the key out to accept the default 16.

Example fix

# before
Search(rank={'$knn': {'query': emb, 'limit': top_k_str}})   # '16' -> TypeError

# after
Search(rank={'$knn': {'query': emb, 'limit': int(top_k_str)}})

top_k = int(knn_opts.pop('limit', 16))
Search(rank={'$knn': {'query': emb, 'limit': top_k, **knn_opts}})

When it happens

Trigger: {'$knn': {'query': emb, 'limit': '16'}} from JSON config; {'limit': 16.0}; numpy sizing math like {'limit': np.int64(top_k)}.

Common situations: top_k coming from an env var or CLI argument (string); strict JSON decoders emitting floats; numpy constants used as defaults for top-k.

Related errors

• $knn requires a dict, got {type(knn_data).__name__}
• $knn query must be a list, numpy array, or SparseVector dict
• $knn key must be a string, got {type(key).__name__}
• $knn limit must be positive, got {limit}
• $knn return_rank must be a boolean, got {type(return_rank)._

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