Troubleshooting ChromaDB InvalidDimensionException: Resolving the 1536 vs 384 Dimension Mismatch

Diagnosing the InvalidDimensionException When Using OpenAI Embeddings

This exception typically manifests when a collection is populated using ChromaDB’s default embedding pipeline and subsequently queried with an external OpenAI embedding model. In a report involving ChromaDB 0.4.24 and Python 3.11.8, a user encountered this failure during retrieval:

InvalidDimensionException: Embedding dimension 1536 does not match collection dimensionality 384

The underlying issue stems from a mismatch between the embedding function used at document ingestion and the embedding function used at query time. The following pattern illustrates how this mismatch occurs in code:

persistent_client = chromadb.PersistentClient()
collection = persistent_client.create_collection("emp6")

# Adding documents without specifying an embedding function defaults to 384 dimensions
for doc in docs:
    collection.add(
        ids=[str(uuid.uuid1())], metadatas=doc.metadata, documents=doc.page_content
    )

# Querying via LangChain Chroma initialized with OpenAI embeddings (1536 dimensions)
langchain_chroma = Chroma(
    client=persistent_client,
    collection_name="emp6",
    embedding_function=OpenAIEmbeddings(),
)
docs1 = langchain_chroma.similarity_search("What is venture")

This snippet demonstrates creating a collection and adding documents without providing an explicit embedding_function, followed by executing a similarity search through LangChain’s Chroma wrapper configured with OpenAIEmbeddings().

When calling create_collection without an explicit embedding_function parameter, ChromaDB applies its default embedding function, producing vector embeddings with 384 dimensions when documents are added via collection.add(...). When querying that same collection through an interface configured with OpenAIEmbeddings()—such as LangChain’s similarity_search—the incoming query text is converted into a 1536-dimensional vector. Because the existing collection was already indexed at 384 dimensions, ChromaDB rejects the 1536-dimensional query vector with chromadb.errors.InvalidDimensionException.

Sources: [Bug]: InvalidDimensionException: Embedding dimension 1536 does not match collection dimensionality 384

Why ChromaDB Defaults to 384 Dimensions and Enforces Fixed Index Dimensionality

To understand why this mismatch occurs, it helps to look at how ChromaDB handles vector spaces by default. ChromaDB sets a default dimensionality of 384 because its built-in embedder, DefaultEmbeddingFunction, uses the Sentence Transformers model all-MiniLM-L6-v2, which generates 384-dimensional embeddings. When a collection is initialized using create_collection or get_or_create_collection without specifying the embedding_function parameter, ChromaDB applies this default embedder and sets the collection dimensionality to 384.

ChromaDB enforces strict dimensionality consistency across all records. By default, the underlying vector index is an HNSW graph index constructed for a single, fixed coordinate space, meaning a collection cannot store or query mixed-dimension vectors.

Furthermore, collection dimensionality cannot be modified in place once initialized. If an operation—including add, upsert, update, or query—attempts to pass embeddings that do not match the collection’s expected dimensionality, ChromaDB rejects the operation and raises chromadb.errors.InvalidDimensionException.

Sources: Embedding Functions – Chroma Docs, Adding Data to Chroma Collections – Chroma Docs, Configure Collections – Chroma Docs, chromadb.errors.InvalidDimensionException: Dimensionality of (512) does not match index dimensionality (768) ·, Sentence Transformer – Chroma Docs

Configuring ChromaDB Collections with OpenAI's 1536-Dimension Embedding Function

To prevent this conflict and ensure your collection accepts 1536-dimensional vectors, you must explicitly supply an embedding function during collection creation. In Python, the chromadb package includes built-in wrappers for providers, allowing you to import OpenAIEmbeddingFunction directly from chromadb.utils.embedding_functions. You must also set your OPENAI_API_KEY environment variable.

When calling create_collection, link the embedding function to the collection using the embedding_function parameter:

# Set your OPENAI_API_KEY environment variable
from chromadb.utils.embedding_functions import OpenAIEmbeddingFunction

collection = client.create_collection(
    name="my_collection",
    embedding_function=OpenAIEmbeddingFunction(
        model_name="text-embedding-3-small"
    ),
)

# ChromaDB will use OpenAIEmbeddingFunction to embed your documents
collection.add(
    ids=["id1", "id2"],
    documents=["doc1", "doc2"],
)

This configuration ensures ChromaDB automatically invokes OpenAIEmbeddingFunction to generate vector representations whenever you call add, update, upsert, or query on the collection using raw text documents.

For TypeScript applications, install the provider package using a package manager (such as npm install @chroma-core/openai, pnpm add @chroma-core/openai, bun add @chroma-core/openai, or yarn add @chroma-core/openai). You can then pass the initialized instance to createCollection:

// Set your OPENAI_API_KEY environment variable
import { OpenAIEmbeddingFunction } from "@chroma-core/openai";

collection = await client.createCollection({
  name: "my_collection",
  embedding_function: new OpenAIEmbeddingFunction({
    modelName: "text-embedding-3-small",
  }),
});

await collection.add({
  ids: ["id1", "id2"],
  documents: ["doc1", "doc2"],
});

This TypeScript setup links OpenAIEmbeddingFunction to the collection so that document insertions and queries are embedded using the specified model rather than the default.

In environments using the Rust client, embedding functions are not attached to the collection; instead, embeddings must be generated separately with your provider SDK and passed directly into calls such as add and query.

Sources: Embedding Functions – Chroma Docs

Deleting, Recreating, and Re-indexing Data in ChromaDB

Once an appropriately configured collection is in place—or when recreating one from scratch—you can safely begin populating it. When inserting records into a collection, ChromaDB raises chromadb.errors.InvalidDimensionException if the supplied embeddings do not match the dimensionality of embeddings already in the collection. Additionally, attempting to re-add a record using an ID that already exists in the collection will be ignored without raising an error; overwriting existing data instead requires updating the data.

To index new records into a collection, use .add. Each record requires a unique string ID, and you must supply either documents, embeddings, or both. Metadata is optional and can contain strings, integers, floats, booleans, or arrays of those types (empty arrays are not permitted, and all elements in an array must share the same type).

If you pass only documents, ChromaDB automatically computes embeddings using the collection’s configured embedding_function:

collection.add(
    ids=["id1", "id2", "id3"],
    documents=["lorem ipsum...", "doc2", "doc3"],
    metadatas=[{"chapter": 3, "verse": 16}, {"chapter": 3, "verse": 5}, {"chapter": 29, "verse": 11}],
)

This call generates embeddings for each document via the configured collection embedding_function before inserting them.

If embeddings are precomputed, you can provide them alongside documents. ChromaDB stores the provided embeddings as-is without re-embedding:

collection.add(
    ids=["id1", "id2", "id3"],
    embeddings=[[1.1, 2.3, 3.2], [4.5, 6.9, 4.4], [1.1, 2.3, 3.2]],
    documents=["doc1", "doc2", "doc3"],
    metadatas=[{"chapter": 3, "verse": 16}, {"chapter": 3, "verse": 5}, {"chapter": 29, "verse": 11}],
)

This method is used when you already have vector representations and want to avoid recalculating embeddings during ingestion. If your documents are stored externally (such as large images or videos), you can also pass only ids, embeddings, and metadatas, using the IDs to link the stored vectors back to external files.

Sources: Adding Data to Chroma Collections – Chroma Docs

Closing thoughts

Ultimately, this error highlights the hidden hazard of ChromaDB’s default behavior: while falling back to a 384-dimensional model simplifies initial prototyping, it makes multi-tool pipelines—especially those bridging LangChain and OpenAI—deceptively fragile. Because Chroma’s underlying HNSW index enforces a strict, immutable coordinate space that cannot be modified in place, treating the embedding function as an optional setting is a risky architectural shortcut rather than a true convenience. Developers should view embedding function configuration as a mandatory schema definition from day one, explicitly establishing the expected dimensionality at collection creation to avoid the costly necessity of tearing down and re-indexing stored data.

Frequently Asked Questions

What causes the error ‘Embedding dimension 1536 does not match collection dimensionality 384’ in ChromaDB?

This error occurs when a collection is created without an explicit embedding function, defaulting to 384 dimensions, and is subsequently queried with an external model like OpenAI that generates 1536-dimensional embeddings.

Why does ChromaDB default to 384 dimensions?

ChromaDB sets a default dimensionality of 384 because its built-in DefaultEmbeddingFunction relies on the Sentence Transformers model all-MiniLM-L6-v2, which outputs 384-dimensional vectors.

Can you modify the dimensionality of an existing ChromaDB collection?

No, collection dimensionality cannot be modified in place once initialized. ChromaDB’s underlying HNSW index enforces a fixed coordinate space, and any operation supplying mismatched vector dimensions will trigger an InvalidDimensionException.

How can you configure a collection in Python to accept 1536-dimensional OpenAI embeddings?

You can import OpenAIEmbeddingFunction from chromadb.utils.embedding_functions and pass it to the embedding_function parameter when calling create_collection, while ensuring the OPENAI_API_KEY environment variable is set.

Keep reading: LLM Agents & Tooling

• Troubleshooting CrewAI ValidationError: Please Provide an OpenAI API Key — Fix CrewAI ValidationError: Please provide an OpenAI API key when setting memory=True by providing an OPENAI_API_KEY or configuring a custom embedder.
• Troubleshooting LangGraph InvalidUpdateError: Resolving Concurrent State Updates with Annotated Reducers — Fix langgraph.errors.InvalidUpdateError in LangGraph. Learn how to resolve concurrent state write collisions using Annotated keys and reducer…
• Troubleshooting LangChain OutputParserException: Both Final Answer and Parse-able Action Produced — Resolve LangChain’s OutputParserException caused when a ReAct agent outputs both an action and final answer. Learn the root causes and best fixes.
• Resolving Pydantic State Deserialization Failures in LangGraph Checkpointers — Pydantic state turning into a raw dict in LangGraph checkpoints? Four causes: msgpack allowlist, unimportable classes, schema drift, unserializable…

All guides in this series: LLM Agent Guides: LangChain, LangGraph & AI Tooling