Chroma (Vector Database, Rust core)

WHENSwitching the EmbeddingFunction on an existing collection (e.g. ada-002 1536d → text-embedding-3-large 3072d).

ACTIONDo NOT expect in-place dimension changes — you must create_collection(new_name) with the new EF, iterate the old collection regenerating all vectors, and write to the new collection.

CONSEQUENCEDimensionality is latched at first write (local_hnsw.py:222-233 _ensure_index sets _dimensionality; mismatched dim then raises InvalidDimensionException). HNSW graph structure is dim-bound and not resizable. Forcing different-dim writes raises a hard exception and the entire batch rolls back.

WHENDeploying Chroma outside Colab (production servers, Docker images, local dev).

ACTIONFirst confirm the host system has sqlite3.sqlite_version_info ≥ (3, 35, 0); if not, install pysqlite3-binary and swap it manually — outside Colab, chromadb does not auto hot-swap.

CONSEQUENCEchromadb/__init__.py:137-155 checks the SQLite version at import time; below 3.35.0 it raises RuntimeError on the non-Colab path, and the entire chromadb module fails to import.

WHENDeploying a Chroma v1.0.0+ server to production.

ACTIONDo NOT rely on Chroma's built-in auth provider — since v1.0.0 the server no longer ships built-in auth; you must front it with a reverse proxy (nginx/Traefik) or an external auth gateway.

CONSEQUENCEIf you configure chroma_server_auth_provider per old docs, v1.0.0+ images will not enable any auth and the service may be fully open, exposing it to unauthenticated access.