{"record":{"id":"1cea43a8666a22b8","repo":"chroma-core/chroma","slug":"expected-embeddings-to-be-a-list-of-floats-or-ints","errorCode":null,"errorMessage":"Expected embeddings to be a list of floats or ints, a list of lists, a numpy array, or a list of numpy arrays, got {target}","messagePattern":"Expected embeddings to be a list of floats or ints, a list of lists, a numpy array, or a list of numpy arrays, got (.+?)","errorType":"validation","errorClass":"ValueError","httpStatus":null,"severity":"error","filePath":"chromadb/api/types.py","lineNumber":251,"sourceCode":"\n    if isinstance(target, np.ndarray):\n        if target.ndim == 1:\n            return [target]\n        elif target.ndim == 2:\n            return [row for row in target]\n    elif isinstance(target, list):\n        # One PyEmbedding\n        if isinstance(target[0], (int, float)) and not isinstance(target[0], bool):\n            return [np.array(target, dtype=np.float32)]\n        elif isinstance(target[0], np.ndarray):\n            return cast(Embeddings, target)\n        elif isinstance(target[0], list):\n            if isinstance(target[0][0], (int, float)) and not isinstance(\n                target[0][0], bool\n            ):\n                return [np.array(row, dtype=np.float32) for row in target]\n\n    raise ValueError(\n        f\"Expected embeddings to be a list of floats or ints, a list of lists, a numpy array, or a list of numpy arrays, got {target}\"\n    )\n\n\n# Metadatas\nMetadatas = List[Metadata]\n\nCollectionMetadata = Dict[str, Any]\nUpdateCollectionMetadata = UpdateMetadata\n\n\ndef normalize_metadata(metadata: Optional[Metadata]) -> Optional[Metadata]:\n    \"\"\"\n    Normalize metadata by converting dict-format sparse vectors to SparseVector instances.\n\n    Accepts:\n    - SparseVector instances (pass through)\n    - Dict with #type='sparse_vector' (convert to SparseVector)","sourceCodeStart":233,"sourceCodeEnd":269,"githubUrl":"https://github.com/chroma-core/chroma/blob/aecdd12c8a891610db8653630b066b32ceb678b5/chromadb/api/types.py#L233-L269","documentation":"normalize_embeddings accepts exactly four shapes: a 1-D or 2-D numpy array, a flat list of ints/floats (a single embedding), a list of numpy arrays, or a list of lists of ints/floats. Everything else — strings, bools, extra nesting, tensors, arbitrary objects — falls through every branch to ValueError('Expected embeddings to be a list of floats or ints, a list of lists, a numpy array, or a list of numpy arrays').","triggerScenarios":"coll.add(embeddings=[['0.1','0.2']]) (numeric strings), embeddings=[True, False] (bools are explicitly rejected), embeddings=[[[0.1],[0.2]]] (three levels of nesting), or passing a torch.Tensor / pandas object directly.","commonSituations":"Embeddings loaded from JSON/CSV where numbers deserialize as strings; passing tensors without .tolist()/numpy(); bool masks mistaken for float vectors; wrapping a single vector in one bracket pair too many.","solutions":["Convert before the call: np.asarray(embeddings, dtype=np.float32) shaped 1-D or 2-D, or [[float(x) for x in v] for v in vecs]","For tensors: tensor.detach().cpu().numpy() (or .tolist()) before passing","Validate the first element's type (int/float excluding bool, np.ndarray, or list of numbers) before sending"],"exampleFix":"// before\ncoll.add(ids=['1'], embeddings=[['0.1', '0.2']])  # strings -> ValueError\n\n// after\nimport numpy as np\nemb = np.asarray([[0.1, 0.2]], dtype=np.float32)\ncoll.add(ids=['1'], embeddings=emb)","handlingStrategy":"type-guard","validationCode":"import numpy as np\n\ndef to_embeddings(value):\n    arr = np.asarray(value, dtype=np.float32)\n    if arr.ndim == 1:\n        arr = arr.reshape(1, -1)\n    if arr.ndim != 2 or arr.shape[0] == 0:\n        raise ValueError(f'cannot interpret {type(value)} as embeddings')\n    return arr\n\ncoll.add(ids=ids, embeddings=to_embeddings(raw))","typeGuard":"import numpy as np\n\ndef is_normalizable_embeddings(v) -> bool:\n    if isinstance(v, np.ndarray):\n        return v.ndim in (1, 2) and v.size > 0\n    if isinstance(v, list) and len(v) > 0:\n        first = v[0]\n        if isinstance(first, (int, float)) and not isinstance(first, bool):\n            return True\n        if isinstance(first, np.ndarray):\n            return True\n        if (isinstance(first, list) and first\n                and isinstance(first[0], (int, float))\n                and not isinstance(first[0], bool)):\n            return True\n    return False","tryCatchPattern":"try:\n    coll.add(ids=ids, embeddings=raw)\nexcept ValueError as e:\n    if 'Expected embeddings' not in str(e):\n        raise\n    coll.add(ids=ids, embeddings=np.asarray(raw, dtype=np.float32))","preventionTips":["Convert embeddings to a 2-D float32 numpy array at your system boundary (JSON load, CSV parse, tensor export)","Never pass torch tensors or string-typed numbers directly","Add a unit test asserting is_normalizable_embeddings on every producer's output"],"tags":["chroma","embeddings","type-validation","numpy","input-format"],"backgroundTag":"invalid-embeddings-format","analyzedSha":"aecdd12c8a891610db8653630b066b32ceb678b5","analyzedAt":"2026-08-16T21:53:27.228Z","schemaVersion":2},"datasetVersion":"2026-08-16T23:17:17.608Z"}