{"record":{"id":"0f95a31046247076","repo":"chroma-core/chroma","slug":"expected-include-to-be-a-list-got-include","errorCode":null,"errorMessage":"Expected include to be a list, got {include}","messagePattern":"Expected include to be a list, got (.+?)","errorType":"validation","errorClass":"ValueError","httpStatus":null,"severity":"error","filePath":"chromadb/api/types.py","lineNumber":1340,"sourceCode":"            for where_document_expression in operand:\n                validate_where_document(where_document_expression)\n        # Value is $contains/$not_contains/$regex/$not_regex operator\n        elif not isinstance(operand, str):\n            raise ValueError(\n                f\"Expected where document operand value for operator {operator} to be a str, got {operand}\"\n            )\n        elif len(operand) == 0:\n            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:","sourceCodeStart":1322,"sourceCodeEnd":1358,"githubUrl":"https://github.com/chroma-core/chroma/blob/aecdd12c8a891610db8653630b066b32ceb678b5/chromadb/api/types.py#L1322-L1358","documentation":"The include parameter of collection.get/query must be a Python list. validate_include rejects any non-list (a bare string, tuple, set, or None) with this ValueError. Valid items are the literals documents, embeddings, metadatas, distances, uris, data.","triggerScenarios":"collection.get(include=\"documents\") (bare string instead of list), include=(\"documents\", \"metadatas\") (tuple — fails isinstance(x, list) even though it looks array-like), or include=None reaching validation.","commonSituations":"Muscle memory from APIs that accept a single string; JSON configs deserialized as a string instead of an array; typed clients (TypeScript/Java) serializing a one-element array as a scalar.","solutions":["Wrap the value in a list: include=[\"documents\"]","If the value may arrive as either form, normalize first: include = [include] if isinstance(include, str) else list(include)","Omit include entirely to accept the default (documents + metadatas) when you don't need custom fields"],"exampleFix":"# before\nresults = collection.get(ids=[\"1\"], include=\"metadatas\")\n\n# after\nresults = collection.get(ids=[\"1\"], include=[\"metadatas\"])","handlingStrategy":"type-guard","validationCode":"def normalize_include(include):\n    if include is None:\n        return [\"documents\", \"metadatas\"]\n    if isinstance(include, str):\n        include = [include]\n    if not isinstance(include, list):\n        raise TypeError(f\"include must be a list, got {type(include).__name__}\")\n    return list(include)\n\nres = collection.get(ids=ids, include=normalize_include(raw_include))","typeGuard":"from typing import Any\n\ndef is_valid_include(include: Any) -> bool:\n    return isinstance(include, list) and all(isinstance(i, str) for i in include)","tryCatchPattern":"try:\n    res = collection.get(ids=ids, include=include)\nexcept ValueError as e:\n    if \"Expected include to be a list\" in str(e) and isinstance(include, str):\n        res = collection.get(ids=ids, include=[include])  # self-heal a bare string\n    else:\n        raise","preventionTips":["Always write include as a list literal, even for one field","Normalize untyped config/JSON inputs with a helper before calling the API","Rely on the typed client signatures (List[Literal[...]]) and mypy to catch this at write time"],"tags":["chromadb","include-parameter","type-mismatch","input-validation"],"backgroundTag":"invalid-query-parameter","analyzedSha":"aecdd12c8a891610db8653630b066b32ceb678b5","analyzedAt":"2026-08-16T21:53:27.228Z","schemaVersion":2},"datasetVersion":"2026-08-16T23:17:17.608Z"}