How to Fix ValueError: Embedding dimension does not match collection dimension (ChromaDB)

Quick Answer: This error occurs when you try to insert or query embeddings whose vector size (e.g., 1536 for text-embedding-ada-002) does not match the dimensionality defined when the ChromaDB collection was first created. The fastest fix is to delete the existing collection and recreate it with an embedding model that matches your current vector dimensions.

What Causes This Error

• Switching embedding models (e.g., from OpenAI text-embedding-ada-002 with 1536 dimensions to text-embedding-3-large with 3072 dimensions) without resetting the collection.
• Using a local model like all-MiniLM-L6-v2 (384 dimensions) while the collection expects a different size.
• Implicitly creating a collection with a default embedding function and then passing custom embeddings of a different size.
• Reusing a persistent storage directory (persist_directory) containing an old collection schema.

Step-by-Step Fixes

Fix 1: Fix 1: Delete and Recreate the Collection

Identify the collection name causing the mismatch.,Call client.delete_collection(name='your_collection_name') in your code.,Recreate the collection using client.create_collection(name='your_collection_name') with the correct embedding function or dimension size.

Fix 2: Fix 2: Align the Embedding Model

Check which embedding model generated the vectors you are trying to add.,Ensure your ChromaDB collection's embedding function matches that exact model.,If changing models, ensure you explicitly configure the correct model in your application initialization.

Fix 3: Fix 3: Clear Persistent Storage Directory

Locate your ChromaDB persistent storage directory on disk.,Stop your application running ChromaDB.,Delete the contents of the persistence folder to clear out legacy collection schemas and start fresh.

Advanced Fixes

Advanced Fix 1: Advanced: Programmatic Schema Migration via New Collection

Create a new collection with a temporary name and the correct dimension schema.,Extract valid documents, metadatas, and embeddings from the old collection (if accessible).,Batch insert the data into the new collection, drop the old collection, and rename or alias the new one.

FAQs

Q: Can I change the dimension of an existing ChromaDB collection without deleting it?

A: No, ChromaDB collections enforce a strict fixed-dimension schema upon creation for indexing efficiency. You must delete and recreate the collection to change dimensions.

Q: How do I check the dimension of an existing ChromaDB collection?

A: You can inspect collection parameters or run a test query/peek to see existing vector shapes, though checking the initialization code of your embedding function is usually the most reliable method.