{"record":{"id":"82570777f105c7ea","repo":"chroma-core/chroma","slug":"expected-requested-number-of-results-to-be-a-int","errorCode":null,"errorMessage":"Expected requested number of results to be a int, got {n_results}","messagePattern":"Expected requested number of results to be a int, got (.+?)","errorType":"validation","errorClass":"ValueError","httpStatus":null,"severity":"error","filePath":"chromadb/api/types.py","lineNumber":1362,"sourceCode":"\n        # Get the valid items from the Literal type inside the List\n        valid_items = get_args(get_args(Include)[0])\n        if item not in valid_items:\n            raise ValueError(\n                f\"Expected include item to be one of {', '.join(valid_items)}, got {item}\"\n            )\n\n        if dissalowed is not None and any(item == e for e in dissalowed):\n            raise ValueError(\n                f\"Include item cannot be one of {', '.join(dissalowed)}, got {item}\"\n            )\n\n\ndef validate_n_results(n_results: int) -> int:\n    \"\"\"Validates n_results to ensure it is a positive Integer. Since hnswlib does not allow n_results to be negative.\"\"\"\n    # Check Number of requested results\n    if not isinstance(n_results, int):\n        raise ValueError(\n            f\"Expected requested number of results to be a int, got {n_results}\"\n        )\n    if n_results <= 0:\n        raise TypeError(\n            f\"Number of requested results {n_results}, cannot be negative, or zero.\"\n        )\n    return n_results\n\n\ndef validate_embeddings(embeddings: Embeddings) -> Embeddings:\n    \"\"\"Validates embeddings to ensure it is a list of numpy arrays of ints, or floats\"\"\"\n    if not isinstance(embeddings, (list, np.ndarray)):\n        raise ValueError(\n            f\"Expected embeddings to be a list, got {type(embeddings).__name__}\"\n        )\n    if len(embeddings) == 0:\n        raise ValueError(\n            f\"Expected embeddings to be a list with at least one item, got {len(embeddings)} embeddings\"","sourceCodeStart":1344,"sourceCodeEnd":1380,"githubUrl":"https://github.com/chroma-core/chroma/blob/aecdd12c8a891610db8653630b066b32ceb678b5/chromadb/api/types.py#L1344-L1380","documentation":"validate_n_results requires n_results to be a Python int. A string (\"5\"), float (5.0), numpy integer (np.int64(5)), or None fails the isinstance check and raises this ValueError. Note that bool passes (bool subclasses int) but is almost never what you want.","triggerScenarios":"collection.query(query_texts=..., n_results=\"10\") from an un-cooked CLI arg or HTTP query param; n_results=5.0 from a config parsed as float; n_results=np.int64(k) from numpy-derived top-k computations.","commonSituations":"CLI tools and web handlers passing string parameters straight through; YAML/JSON configs where 5 parses as float 5.0; pandas/numpy code computing k as np.int64; LangChain-style wrappers forwarding user input unvalidated.","solutions":["Coerce before the call: n_results=int(n_results)","Parse CLI/HTTP params explicitly: parser.add_argument('--k', type=int)","Guard numpy scalars: int(np.int64(k)) — numpy integers are not Python ints and fail the isinstance check"],"exampleFix":"# before\nk = config.get(\"top_k\", 5.0)\nresults = collection.query(query_embeddings=[q], n_results=k)\n\n# after\nk = int(config.get(\"top_k\", 5))\nresults = collection.query(query_embeddings=[q], n_results=k)","handlingStrategy":"type-guard","validationCode":"def coerce_n_results(n) -> int:\n    if isinstance(n, bool):\n        raise TypeError(\"n_results must be an int, not bool\")\n    if not isinstance(n, int):\n        n = int(n)  # accepts \"5\", 5.0, np.int64(5)\n    if n <= 0:\n        raise ValueError(\"n_results must be >= 1\")\n    return n\n\nres = collection.query(query_embeddings=[q], n_results=coerce_n_results(raw_k))","typeGuard":"import numpy as np\n\ndef is_valid_n_results(n) -> bool:\n    return (isinstance(n, int) or isinstance(n, np.integer)) and not isinstance(n, bool) and n > 0","tryCatchPattern":"try:\n    res = collection.query(query_texts=[q], n_results=k)\nexcept ValueError as e:\n    if \"requested number of results\" in str(e) and str(k).lstrip(\"+-\").isdigit():\n        res = collection.query(query_texts=[q], n_results=int(k))\n    else:\n        raise","preventionTips":["Declare CLI/HTTP parameters as integers at the boundary (type=int, int(...) in the handler)","Cast numpy scalars with int() before passing top-k","Beware YAML configs parsing 5 as 5.0 — coerce once at load time"],"tags":["chromadb","n-results","top-k","type-mismatch"],"backgroundTag":"invalid-limit-parameter","analyzedSha":"aecdd12c8a891610db8653630b066b32ceb678b5","analyzedAt":"2026-08-16T21:53:27.228Z","schemaVersion":2},"datasetVersion":"2026-08-16T23:17:17.608Z"}