[DOC] `Collection.add` / `query` docstrings list ValueErrors the client never raises

Author: siddharthgaur1Created Sep 13, 2026Updated Sep 13, 2026

The Raises: sections of Collection.add and Collection.query (and the same text in AsyncCollection) describe three errors that chromadb 1.5.9 does not raise. The generated reference page reference/python/collection.mdx repeats them, and in two of the three cases the user guide already says the opposite.

Docstring says	What happens (1.5.9)	Guide says
`add`: "ValueError: If an ID already exists."	No error. The existing record is kept and the new one is dropped.	`add-data.mdx:182`: "it will be ignored without throwing an error"
`add`: "ValueError: If embeddings and documents are both provided."	Accepted, both stored. `types.py` explicitly allows documents alongside embeddings.	`add-data.mdx:57`, `:60`: pass both, stored as-is
`query`: "ValueError: If multiple query input types are provided."	No error. With `query_embeddings` and `query_texts` both given, the embeddings are used and the texts are ignored.	—

All three reproduce with EphemeralClient and with HttpClient against chroma run. The existing-ID add and the query case also reproduce with AsyncHttpClient.

Reproduction

python

import chromadb

col = chromadb.EphemeralClient().create_collection("repro", embedding_function=None)
e = [[0.1, 0.2, 0.3]]

col.add(ids=["a"], embeddings=e, documents=["first"])
col.add(ids=["a"], embeddings=[[0.9, 0.9, 0.9]], documents=["second"])  # documented to raise
print(col.get(ids=["a"])["documents"])  # ['first']

col.add(ids=["b"], embeddings=e, documents=["doc"])  # documented to raise; accepted

print(col.query(query_embeddings=e, query_texts=["unrelated"], n_results=1)["ids"])  # documented to raise; texts ignored

Where

chromadb/api/models/Collection.py: add Raises (lines 122, 124 on main), query Raises (268)
chromadb/api/models/AsyncCollection.py: add Raises (84-85), query Raises (249-251)
docs/mintlify/reference/python/collection.mdx: generated from the above by docs/scripts/generate_python_reference.py

Versions

chromadb 1.5.9 (latest on PyPI), Python 3.11.6, Windows 11. Line numbers are from main at a7920e9.

Proposed fix

For add, the behaviour matches the guide, so only the docstrings are wrong: drop the two lines, and state that an existing ID is ignored, pointing at upsert/update. Then regenerate collection.mdx.

query is less clear-cut. Silently ignoring query_texts when embeddings are also passed is easy to miss, so it could be either a docstring fix or a real check. Raising now would break callers that pass both today. Which would you prefer?

I can open a PR for the docstring changes.

Source: chroma-core/chroma

View original on GitHub View discussion on GitHub