{"record":{"id":"bf2ab52481fba3d7","repo":"chroma-core/chroma","slug":"knn-limit-must-be-positive-got-limit","errorCode":null,"errorMessage":"$knn limit must be positive, got {limit}","messagePattern":"\\$knn limit must be positive, got (.+?)","errorType":"exception","errorClass":"ValueError","httpStatus":null,"severity":"error","filePath":"chromadb/execution/expression/operator.py","lineNumber":735,"sourceCode":"\n                query = normalized[0]\n\n            else:\n                raise TypeError(\n                    f\"$knn query must be a list, numpy array, or SparseVector dict, got {type(query).__name__}\"\n                )\n\n            key = knn_data.get(\"key\", \"#embedding\")\n            if not isinstance(key, str):\n                raise TypeError(f\"$knn key must be a string, got {type(key).__name__}\")\n\n            limit = knn_data.get(\"limit\", 16)\n            if not isinstance(limit, int):\n                raise TypeError(\n                    f\"$knn limit must be an integer, got {type(limit).__name__}\"\n                )\n            if limit <= 0:\n                raise ValueError(f\"$knn limit must be positive, got {limit}\")\n\n            return_rank = knn_data.get(\"return_rank\", False)\n            if not isinstance(return_rank, bool):\n                raise TypeError(\n                    f\"$knn return_rank must be a boolean, got {type(return_rank).__name__}\"\n                )\n\n            return Knn(\n                query=query,\n                key=key,\n                limit=limit,\n                default=knn_data.get(\"default\"),\n                return_rank=return_rank,\n            )\n\n        elif op == \"$sum\":\n            ranks_data = data[\"$sum\"]\n            if not isinstance(ranks_data, (list, tuple)):","sourceCodeStart":717,"sourceCodeEnd":753,"githubUrl":"https://github.com/chroma-core/chroma/blob/aecdd12c8a891610db8653630b066b32ceb678b5/chromadb/execution/expression/operator.py#L717-L753","documentation":"$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.","triggerScenarios":"{'$knn': {'query': emb, 'limit': 0}}; {'limit': -5}; computed sizes like top_k = max(0, remaining) flooring to 0 on the last page.","commonSituations":"Dynamically sizing top_k from remaining result slots; users sending top_k=0 meaning 'no results'; defaults of 0 instead of omitting the key.","solutions":["Omit 'limit' (default 16) or pass a value >= 1.","Clamp computed values: max(1, top_k).","Return early for zero-result requests instead of building a $knn node."],"exampleFix":"# before\nSearch(rank={'$knn': {'query': emb, 'limit': max(0, remaining)}})   # 0 -> ValueError\n\n# after\nSearch(rank={'$knn': {'query': emb, 'limit': max(1, remaining)}})","handlingStrategy":"validation","validationCode":"top_k = knn_opts.get('limit', 16)\nif top_k is not None and top_k < 1:\n    raise ValueError(f'$knn limit must be >= 1, got {top_k}')","typeGuard":null,"tryCatchPattern":null,"preventionTips":["Clamp user-supplied top_k to a sane range (e.g. 1..1000).","Treat 0 as 'use the default' or reject at request validation.","Test the top_k=0 edge case explicitly."],"tags":["validation","valueerror","knn","top-k","chromadb"],"backgroundTag":"out-of-range-value","analyzedSha":"aecdd12c8a891610db8653630b066b32ceb678b5","analyzedAt":"2026-08-16T21:53:27.228Z","schemaVersion":2},"datasetVersion":"2026-08-16T23:17:17.608Z"}