{"record":{"id":"ab6d1f88f8a8d801","repo":"chroma-core/chroma","slug":"knn-limit-must-be-an-integer-got-type-limit","errorCode":null,"errorMessage":"$knn limit must be an integer, got {type(limit).__name__}","messagePattern":"\\$knn limit must be an integer, got (.+?)","errorType":"exception","errorClass":"TypeError","httpStatus":null,"severity":"error","filePath":"chromadb/execution/expression/operator.py","lineNumber":731,"sourceCode":"                    raise ValueError(\"$knn requires exactly one query embedding\")\n\n                # Validate the normalized version\n                validate_embeddings(normalized)\n\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            )","sourceCodeStart":713,"sourceCodeEnd":749,"githubUrl":"https://github.com/chroma-core/chroma/blob/aecdd12c8a891610db8653630b066b32ceb678b5/chromadb/execution/expression/operator.py#L713-L749","documentation":"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.","triggerScenarios":"{'$knn': {'query': emb, 'limit': '16'}} from JSON config; {'limit': 16.0}; numpy sizing math like {'limit': np.int64(top_k)}.","commonSituations":"top_k coming from an env var or CLI argument (string); strict JSON decoders emitting floats; numpy constants used as defaults for top-k.","solutions":["Cast at the boundary: {'limit': int(top_k)}.","Type top_k as int in your config/CLI parsing layer.","Leave the key out to accept the default 16."],"exampleFix":"# before\nSearch(rank={'$knn': {'query': emb, 'limit': top_k_str}})   # '16' -> TypeError\n\n# after\nSearch(rank={'$knn': {'query': emb, 'limit': int(top_k_str)}})","handlingStrategy":"validation","validationCode":"top_k = int(knn_opts.pop('limit', 16))\nSearch(rank={'$knn': {'query': emb, 'limit': top_k, **knn_opts}})","typeGuard":null,"tryCatchPattern":null,"preventionTips":["Coerce CLI/env/config ints once, at the edge.","Remember two different limits exist: $knn's fetch size and Search's pagination Limit.","Convert numpy scalars with int() before payload construction."],"tags":["validation","typeerror","knn","top-k","chromadb"],"backgroundTag":"type-validation-failed","analyzedSha":"aecdd12c8a891610db8653630b066b32ceb678b5","analyzedAt":"2026-08-16T21:53:27.228Z","schemaVersion":2},"datasetVersion":"2026-08-16T23:17:17.608Z"}