Skip to main content

🔍 Troubleshooting

This page is a list of common gotchas or issues and how to fix them.

If you don't see your problem listed here, please also search the Github Issues.

Using .get or .query, embeddings say None​

This is actually not an error. Embeddings are quite large and heavy to send back. Most application don't use the underlying embeddings and so, by default, chroma does not send them back.

To send them back: add include=["embeddings", "documents", "metadatas", "distances"] to your query to return all information.

For example:

results = collection.query(
    query_texts="hello",
    n_results=1,
    include=["embeddings", "documents", "metadatas", "distances"],
)
note

We may change None to something else to more clearly communicate why they were not returned.

Your index resets back to just a few number of records​

Users report that they are using Chroma, happily adding data, and then they go to check the count() or query() and only a single item or a very small fraction of their data is in Chroma.

Chroma has 3 clients: Ephemeral, Persistent, and Http. The Ephemeral and Persistent clients should treated as singletons.

Here is what commonly happens.

  1. Create a new Chroma client, #1 saving to ./db, and add 10 items.
  2. Create another new Chroma client, #2 saving to ./db, and add 10 more items. Call this B.
  3. Chroma does not lock the database between clients, each client maintains its own locking structure, so these clients can overwrite each other.

Solution: Don't use multiple Ephemeral or Persistent clients at the same time. Create one client and use it for all your operations.

note

We may add extra logic to warn if multiple in-memory clients are used with the same path.

Build error when running pip install chromadb​

If you encounter an error like this during setup

Failed to build hnswlib
ERROR: Could not build wheels for hnswlib, which is required to install pyproject.toml-based projects

Try these few tips from the community:

  1. If you get the error: clang: error: the clang compiler does not support '-march=native', set this ENV variable, export HNSWLIB_NO_NATIVE=1
  2. If on Mac, install/update xcode dev tools, xcode-select --install
  3. If on Windows, try these steps

SQLite​

Chroma requires SQLite > 3.35, if you encounter issues with having too low of a SQLite version please try the following.

  1. Install the latest version of Python 3.10, sometimes lower versions of python are bundled with older versions of SQLite.
  2. If you are on a Linux system, you can install pysqlite3-binary, pip install pysqlite3-binary and then override the default sqlite3 library before running Chroma with the steps here. Alternatively you can compile SQLite from scratch and replace the library in your python installation with the latest version as documented here.
  3. If you are on Windows, you can manually download the latest version of SQLite from https://www.sqlite.org/download.html and replace the DLL in your python installation's DLLs folder with the latest version. You can find your python installation path by running os.path.dirname(sys.executable) in python.
  4. If you are using a Debian based Docker container, older Debian versions do not have an up to date SQLite, please use bookworm or higher.