{"record":{"id":"1470c8f089ab37b3","repo":"chroma-core/chroma","slug":"expected-include-item-to-be-a-str-got-item","errorCode":null,"errorMessage":"Expected include item to be a str, got {item}","messagePattern":"Expected include item to be a str, got (.+?)","errorType":"validation","errorClass":"ValueError","httpStatus":null,"severity":"error","filePath":"chromadb/api/types.py","lineNumber":1343,"sourceCode":"        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:\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):","sourceCodeStart":1325,"sourceCodeEnd":1361,"githubUrl":"https://github.com/chroma-core/chroma/blob/aecdd12c8a891610db8653630b066b32ceb678b5/chromadb/api/types.py#L1325-L1361","documentation":"Each element of the include list must be a string. validate_include iterates the list and raises this ValueError on the first non-str item (int, None, dict, nested list).","triggerScenarios":"collection.query(..., include=[\"documents\", None]) or include=[\"metadatas\", 1] or a list built with a bug that appends indices/objects, e.g. include += [len(fields)].","commonSituations":"Optional fields appended as None placeholders; list built via zip/map that yields non-strings; deserialized JSON with mixed types; copy-paste leaving a stray comma creating nested lists.","solutions":["Filter/validate before the call: include = [i for i in include if isinstance(i, str)]","Fix the code that appends non-string values into the include list","Check for accidental nesting such as include=[[\"documents\"]]"],"exampleFix":"# before\ninclude = [\"documents\"] + [None if want_meta else \"metadatas\"]\n\n# after\ninclude = [\"documents\"]\nif want_meta:\n    include.append(\"metadatas\")","handlingStrategy":"type-guard","validationCode":"def clean_include(items):\n    cleaned = [i for i in items if isinstance(i, str) and i]\n    if not cleaned:\n        raise ValueError(\"include list has no valid string items\")\n    return cleaned\n\nres = collection.get(ids=ids, include=clean_include(raw_items))","typeGuard":"def is_valid_include(include) -> bool:\n    return isinstance(include, list) and bool(include) and all(isinstance(i, str) for i in include)","tryCatchPattern":"try:\n    res = collection.query(query_embeddings=[q], include=include, n_results=5)\nexcept ValueError as e:\n    if \"include item to be a str\" in str(e):\n        include = [i for i in include if isinstance(i, str)]\n        res = collection.query(query_embeddings=[q], include=include, n_results=5)\n    else:\n        raise","preventionTips":["Never append None placeholders into include; build the list conditionally","Validate deserialized JSON include arrays (they may contain numbers/nulls)","Watch for accidental nested lists like [[\"documents\"]]"],"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"}