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.

Chroma JS-Client failures on NextJS projects#

Our default embedding function uses @huggingface/transformers, which depends on binaries that NextJS fails to bundle. If you are running into this issue, you can wrap your nextConfig (in next.config.ts) with the withChroma plugin, which will add the required settings to overcome the bundling issues.

import type { NextConfig } from "next";
import { withChroma } from "chromadb";

const nextConfig: NextConfig = {
  /* config options here */
};

export default withChroma(nextConfig);

Cannot return the results in a contiguous 2D array. Probably ef or M is too small#

This error happens when the HNSW index fails to retrieve the requested number of results for a query, given its structure and your data. he way to resolve this is to either decrease the number of results you request from a query (n_result), or increase the HNSW parameters M, ef_construction, and ef_search. You can read more about HNSW configurations here.

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"],
)

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

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.

Illegal instruction (core dumped)#

If you encounter an error like this during setup and are using Docker - you may have built the library on a machine with a different CPU architecture than the one you are running it on. Try rebuilding the Docker image on the machine you are running it on.

My data directory is too large#

If you were using Chroma prior to v0.5.6, you may be able to significantly shrink your database by vacuuming it. After vacuuming once, automatic pruning (a new feature in v0.5.6) is enabled and will keep your database size in check.