{"record":{"id":"ae17ec275e9d1149","repo":"chroma-core/chroma","slug":"expected-include-item-to-be-one-of-join-vali","errorCode":null,"errorMessage":"Expected include item to be one of {', '.join(valid_items)}, got {item}","messagePattern":"Expected include item to be one of (.+?), got (.+?)","errorType":"validation","errorClass":"ValueError","httpStatus":null,"severity":"error","filePath":"chromadb/api/types.py","lineNumber":1348,"sourceCode":"            raise ValueError(\n                f\"Expected where document operand value for operator {operator} to be a non-empty str\"\n            )\n\n\ndef validate_include(include: Include, dissalowed: Optional[Include] = None) -> None:\n    \"\"\"Validates include to ensure it is a list of strings. Since get does not allow distances, allow_distances is used\n    to control if distances is allowed\"\"\"\n\n    if not isinstance(include, list):\n        raise ValueError(f\"Expected include to be a list, got {include}\")\n    for item in include:\n        if not isinstance(item, str):\n            raise ValueError(f\"Expected include item to be a str, got {item}\")\n\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(","sourceCodeStart":1330,"sourceCodeEnd":1366,"githubUrl":"https://github.com/chroma-core/chroma/blob/aecdd12c8a891610db8653630b066b32ceb678b5/chromadb/api/types.py#L1330-L1366","documentation":"Every include item must be one of the literal values of the Include type: documents, embeddings, metadatas, distances, uris, data. validate_include extracts these via typing.get_args and rejects anything else, including close typos like \"document\", \"embedding\", or \"ids\".","triggerScenarios":"include=[\"document\"] (singular typo), include=[\"ids\"] (ids are always returned and not includable), include=[\"metadata\"], or include=[\"embeddings\", \"score\"]. Raised on collection.get() and collection.query() calls.","commonSituations":"Singular/plural confusion — the API uses plurals (documents, metadatas, embeddings); porting code from other vector DBs whose field names differ (e.g. \"score\" or \"vector\"); auto-complete picking the wrong token.","solutions":["Use exactly one of: \"documents\", \"embeddings\", \"metadatas\", \"distances\", \"uris\", \"data\"","Fix singular typos: \"document\" → \"documents\", \"metadata\" → \"metadatas\"","Remove \"ids\" from include — ids are returned automatically in every result"],"exampleFix":"# before\nresults = collection.query(query_embeddings=[q], include=[\"document\", \"ids\"])\n\n# after\nresults = collection.query(query_embeddings=[q], include=[\"documents\", \"metadatas\"])  # ids always returned","handlingStrategy":"validation","validationCode":"VALID_INCLUDE = {\"documents\", \"embeddings\", \"metadatas\", \"distances\", \"uris\", \"data\"}\n\ndef validate_include_items(include: list[str]) -> list[str]:\n    bad = [i for i in include if i not in VALID_INCLUDE]\n    if bad:\n        raise ValueError(f\"invalid include items {bad}; valid: {sorted(VALID_INCLUDE)}\")\n    return include\n\nres = collection.query(query_embeddings=[q], include=validate_include_items(include), n_results=5)","typeGuard":"from typing import Literal, get_args\nfrom chromadb.api.types import Include\n\nVALID = set(get_args(get_args(Include)[0]))\n\ndef is_valid_include_value(include: list) -> bool:\n    return all(isinstance(i, str) and i in VALID for i in include)","tryCatchPattern":"try:\n    res = collection.get(ids=ids, include=include)\nexcept ValueError as e:\n    if \"Expected include item to be one of\" in str(e):\n        raise ValueError(f\"check plurals: {include}; valid = documents, embeddings, metadatas, distances, uris, data\") from e\n    raise","preventionTips":["Memorize the plural forms: documents, metadatas, embeddings, distances, uris, data","ids are always returned — never put \"ids\" in include","Define constants (INCLUDE_DOCS_META = [\"documents\", \"metadatas\"]) instead of retyping strings"],"tags":["chromadb","include-parameter","invalid-value","typo"],"backgroundTag":"invalid-query-parameter","analyzedSha":"aecdd12c8a891610db8653630b066b32ceb678b5","analyzedAt":"2026-08-16T21:53:27.228Z","schemaVersion":2},"datasetVersion":"2026-08-16T23:17:17.608Z"}