{"record":{"id":"f8478edf5e4f3dfb","repo":"chroma-core/chroma","slug":"expected-embeddings-to-be-a-list-with-at-least-one","errorCode":null,"errorMessage":"Expected embeddings to be a list with at least one item, got {len(embeddings)} embeddings","messagePattern":"Expected embeddings to be a list with at least one item, got (.+?) embeddings","errorType":"validation","errorClass":"ValueError","httpStatus":null,"severity":"error","filePath":"chromadb/api/types.py","lineNumber":1379,"sourceCode":"    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\"\n        )\n    if not all([isinstance(e, np.ndarray) for e in embeddings]):\n        raise ValueError(\n            \"Expected each embedding in the embeddings to be a numpy array, got \"\n            f\"{list(set([type(e).__name__ for e in embeddings]))}\"\n        )\n    for i, embedding in enumerate(embeddings):\n        if embedding.ndim == 0:\n            raise ValueError(\n                f\"Expected a 1-dimensional array, got a 0-dimensional array {embedding}\"\n            )\n        if embedding.size == 0:\n            raise ValueError(\n                f\"Expected each embedding in the embeddings to be a 1-dimensional numpy array with at least 1 int/float value. Got a 1-dimensional numpy array with no values at pos {i}\"\n            )\n\n        if embedding.dtype not in [","sourceCodeStart":1361,"sourceCodeEnd":1397,"githubUrl":"https://github.com/chroma-core/chroma/blob/aecdd12c8a891610db8653630b066b32ceb678b5/chromadb/api/types.py#L1361-L1397","documentation":"validate_embeddings rejects an empty list/ndarray (len == 0). At least one embedding must be present, because there is nothing to add or query otherwise. The message echoes the (zero) count.","triggerScenarios":"collection.add(ids=[], embeddings=[]) or collection.query(query_embeddings=[]) — an upstream batch/text list was empty, e.g. chunking produced 0 chunks, a file read returned no lines, or an empty batch loop iterated once.","commonSituations":"Batch ingestion pipelines that don't skip empty batches; processing small/empty documents with a chunker that emits nothing; guard code missing around 'for each file: add(chunks)'.","solutions":["Skip the add/query call when the batch is empty: if not embeddings: return","Fix the upstream chunking/reading step that produced zero items","Validate input documents before embedding to avoid paying for embeddings that get rejected anyway"],"exampleFix":"# before\ncollection.add(ids=ids, embeddings=embeds)  # embeds == []\n\n# after\nif ids:\n    collection.add(ids=ids, embeddings=embeds)","handlingStrategy":"validation","validationCode":"def assert_non_empty_batch(ids, embeddings, documents=None):\n    if not ids or not embeddings:\n        raise ValueError(\"refusing to call add() with an empty batch\")\n\nif ids and embeddings:\n    collection.add(ids=ids, embeddings=embeddings, documents=documents)","typeGuard":"def is_non_empty_embeddings(v) -> bool:\n    return isinstance(v, (list,)) and len(v) > 0  # ndarray case: len(v) > 0 works for 2-D too","tryCatchPattern":"try:\n    collection.add(ids=ids, embeddings=embeds, documents=docs)\nexcept ValueError as e:\n    if \"at least one item\" in str(e):\n        logger.warning(\"skipped empty embedding batch\")\n    else:\n        raise","preventionTips":["Guard every batch loop with 'if not batch: continue'","Check chunker/loader outputs for zero rows before embedding (saves compute too)","Log len(batch) at ingestion boundaries to catch silent empties"],"tags":["chromadb","embeddings","empty-list","batching"],"backgroundTag":"invalid-embedding-format","analyzedSha":"aecdd12c8a891610db8653630b066b32ceb678b5","analyzedAt":"2026-08-16T21:53:27.228Z","schemaVersion":2},"datasetVersion":"2026-08-16T23:17:17.608Z"}