How to Fix 'embedding dimension mismatch during development' in LlamaIndex (TypeScript)

Embedding dimension mismatch usually means your vector store already contains embeddings created with one model, but your current code is trying to insert or query with a different embedding size. In LlamaIndex TypeScript, this shows up most often during development when you switch embedding models, rebuild part of the app, or reuse a persisted index across runs.

The failure is usually immediate: ingestion works until the first insert() or query(), then you get a runtime error from the vector store or similarity search layer. The exact message varies by backend, but the root problem is always the same: one index expects vectors of length N, and you are sending vectors of length M.

The Most Common Cause

The #1 cause is mixing embedding models across the same index or collection.

For example, you created a Pinecone/Chroma/PGVector collection with text-embedding-3-small and later switched local dev code to text-embedding-3-large, or vice versa. LlamaIndex’s VectorStoreIndex does not auto-migrate old vectors for you.

// BROKEN: collection was built earlier with a different embedding dimension
import { VectorStoreIndex } from "llamaindex";
import { OpenAIEmbedding } from "@llamaindex/openai";

const embedModel = new OpenAIEmbedding({
  model: "text-embedding-3-large", // 3072 dims
});

const index = await VectorStoreIndex.init({
  vectorStore,
  embedModel,
});

await index.insert({
  text: "Policy document about claims handling",
});

// FIXED: use the same embedding model as the existing collection,
// or recreate the collection/index from scratch.
import { VectorStoreIndex } from "llamaindex";
import { OpenAIEmbedding } from "@llamaindex/openai";

const embedModel = new OpenAIEmbedding({
  model: "text-embedding-3-small", // 1536 dims
});

const index = await VectorStoreIndex.init({
  vectorStore,
  embedModel,
});

await index.insert({
  text: "Policy document about claims handling",
});

If you already changed models, do not just “retry.” Delete the old collection or namespace and rebuild it. The stored vectors must match the query-time embedding dimension exactly.

A real-world example looks like this:

Error: Vector dimension mismatch: expected 1536, got 3072

Or from a backend like Pinecone:

PineconeClientError: Vector dimension 3072 does not match the dimension of the index 1536

Other Possible Causes

1) You changed providers without noticing

OpenAI, Cohere, Voyage, Hugging Face, and local models all emit different dimensions. If your .env changed and your app still points at the same vector store, you will hit this immediately.

// Example mismatch
const embedModel = new OpenAIEmbedding({ model: "text-embedding-3-large" });
// but your stored index was built with:
// const embedModel = new OpenAIEmbedding({ model: "text-embedding-3-small" });

2) Your chunk ingestion path uses one embedder and query path uses another

This happens when ingestion runs in one service and search runs in another. One service may use default settings while the other explicitly sets a model.

// Ingestion service
const ingestEmbedder = new OpenAIEmbedding({ model: "text-embedding-3-small" });

// Query service
const queryEmbedder = new OpenAIEmbedding({ model: "text-embedding-3-large" });

Make both services share the same embedding config.

3) You reused an old persisted local store

If you persist Chroma/SQLite/PGVector data locally during development, old embeddings stay on disk even after code changes. Restarting the app does not fix stale vector dimensions.

// Example: persisted path still contains old vectors
const vectorStore = new ChromaVectorStore({
  collectionName: "dev_docs",
  persistDir: "./storage/chroma",
});

Delete ./storage/chroma or create a new collection name when changing models.

4) The vector store schema was created with a fixed dimension

Some backends enforce dimension at schema creation time. If you initialized PGVector or Pinecone with 1536, inserting 3072 will fail even if LlamaIndex code is correct.

-- Example PGVector table tied to one dimension
CREATE TABLE doc_vectors (
  id uuid PRIMARY KEY,
  embedding vector(1536)
);

If you need a different model, create a new table with matching dimensions.

How to Debug It

1. •

   Check the exact embedding model on both sides

   • •Look at ingestion code and query code.
   • •Confirm they use the same class and model name.
   • •In LlamaIndex TypeScript, inspect instances like OpenAIEmbedding, CohereEmbedding, or custom embedders.
2. •

   Print the actual vector length

   • •Log one generated embedding before inserting.
   • •Compare it to what your store expects.

const vec = await embedModel.getTextEmbedding("test string");
console.log(vec.length); // should match your index dimension exactly

3. •

   Inspect the existing store schema

   • •Pinecone index dimension.
   • •PGVector column size.
   • •Chroma collection metadata if applicable.
   • •If it was created previously, assume it is stale until proven otherwise.
4. •

   Rebuild from scratch

   • •Delete the local persistence directory.
   • •Drop/recreate the remote collection/table.
   • •Re-ingest using one known-good model only.

If rebuilding fixes it, your issue was stale data or mixed embeddings. If it does not, your app likely has two different embed configs in separate execution paths.

Prevention

• •Keep embedding configuration in one shared module used by both ingestion and query code.
• •Version your collections by embedding model name, for example:
  • •docs_text_embedding_3_small
  • •docs_text_embedding_3_large
• •When changing models during development, always drop and recreate persisted indexes before testing again.
• •Add a startup check that logs:
  • •embedding provider
  • •model name
  • •expected vector dimension

A simple rule works well in production: one collection equals one embedding dimension. Once you violate that rule, this error will keep coming back until you rebuild cleanly.

Keep learning

• •The complete AI Agents Roadmap — my full 8-step breakdown
• •Free: The AI Agent Starter Kit — PDF checklist + starter code
• •Work with me — I build AI for banks and insurance companies

By Cyprian Aarons, AI Consultant at Topiax.