{"record":{"id":"37a58b903e9ec130","repo":"chroma-core/chroma","slug":"expected-documents-to-be-a-list-got-type-documen","errorCode":null,"errorMessage":"Expected documents to be a list, got {type(documents).__name__}","messagePattern":"Expected documents to be a list, got (.+?)","errorType":"validation","errorClass":"ValueError","httpStatus":null,"severity":"error","filePath":"chromadb/api/types.py","lineNumber":1443,"sourceCode":"        raise ValueError(\n            f\"Expected sparse vectors to be a list, got {type(vectors).__name__}\"\n        )\n    if len(vectors) == 0:\n        raise ValueError(\n            f\"Expected sparse vectors to be a non-empty list, got {len(vectors)} sparse vectors\"\n        )\n    for i, vector in enumerate(vectors):\n        if not isinstance(vector, SparseVector):\n            raise ValueError(\n                f\"Expected SparseVector instance at position {i}, got {type(vector).__name__}\"\n            )\n    return vectors\n\n\ndef validate_documents(documents: Documents, nullable: bool = False) -> None:\n    \"\"\"Validates documents to ensure it is a list of strings\"\"\"\n    if not isinstance(documents, list):\n        raise ValueError(\n            f\"Expected documents to be a list, got {type(documents).__name__}\"\n        )\n    if len(documents) == 0:\n        raise ValueError(\n            f\"Expected documents to be a non-empty list, got {len(documents)} documents\"\n        )\n    for document in documents:\n        # If embeddings are present, some documents can be None\n        if document is None and nullable:\n            continue\n        if not is_document(document):\n            raise ValueError(f\"Expected document to be a str, got {document}\")\n\n\ndef validate_images(images: Images) -> None:\n    \"\"\"Validates images to ensure it is a list of numpy arrays\"\"\"\n    if not isinstance(images, list):\n        raise ValueError(f\"Expected images to be a list, got {type(images).__name__}\")","sourceCodeStart":1425,"sourceCodeEnd":1461,"githubUrl":"https://github.com/chroma-core/chroma/blob/aecdd12c8a891610db8653630b066b32ceb678b5/chromadb/api/types.py#L1425-L1461","documentation":"validate_documents requires the documents argument to be a Python list of strings. A bare string (the most common mistake), tuple, generator, or None raises this ValueError with the type name reported. With nullable=True, individual None entries are allowed, but the outer value must still be a list.","triggerScenarios":"collection.add(ids=[\"1\"], documents=\"hello world\") — one document passed as a bare string instead of [\"hello world\"]; documents=(\"a\", \"b\") as a tuple; documents=some_generator.","commonSituations":"Single-document helpers/upserts where the author forgets the list; treating a long string as already-listed; tuple literals reused from config; iterating a file object directly instead of readlines().","solutions":["Wrap single documents in a list: documents=[\"hello world\"]","Normalize defensively: documents = [documents] if isinstance(documents, str) else list(documents)","Match list lengths — ids, documents, and metadatas must all be equal length"],"exampleFix":"# before\ncollection.add(ids=[\"doc1\"], documents=\"hello world\")\n\n# after\ncollection.add(ids=[\"doc1\"], documents=[\"hello world\"])","handlingStrategy":"type-guard","validationCode":"def normalize_documents(docs):\n    if isinstance(docs, str):\n        docs = [docs]\n    elif not isinstance(docs, list):\n        docs = list(docs)\n    if not docs:\n        raise ValueError(\"documents must be a non-empty list\")\n    return docs\n\ncollection.add(ids=ids, documents=normalize_documents(docs))","typeGuard":"from typing import Any\n\ndef is_document_list(docs: Any) -> bool:\n    return isinstance(docs, list) and all(d is None or isinstance(d, str) for d in docs)","tryCatchPattern":"try:\n    collection.upsert(ids=ids, documents=docs, metadatas=metas)\nexcept ValueError as e:\n    if \"Expected documents to be a list\" in str(e) and isinstance(docs, str):\n        collection.upsert(ids=ids, documents=[docs], metadatas=metas)  # self-heal bare string\n    else:\n        raise","preventionTips":["documents is always a LIST — wrap single strings in [ ]","Keep ids, documents, metadatas the same length","Use a normalize helper at request/config boundaries where scalars sneak in"],"tags":["chromadb","documents","type-mismatch","input-validation"],"backgroundTag":"invalid-document-format","analyzedSha":"aecdd12c8a891610db8653630b066b32ceb678b5","analyzedAt":"2026-08-16T21:53:27.228Z","schemaVersion":2},"datasetVersion":"2026-08-16T23:17:17.608Z"}