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

What the error means

embedding dimension mismatch in production usually means your vector store already contains embeddings of one size, but your current embedding model is producing a different size. In LlamaIndex TypeScript, this shows up when you switch models, redeploy with a different provider, or reuse an old index against a new embedding configuration.

The failure often appears during index.insert(), VectorStoreIndex.fromDocuments(), or retrieval time when the vector DB validates the incoming embedding length against stored vectors.

The Most Common Cause

The #1 cause is simple: you built the index with one embedding model, then queried or inserted with another.

A common production pattern is changing from OpenAI embeddings to a smaller or larger model without rebuilding the index. Vector databases like Pinecone, Qdrant, Weaviate, and pgvector do not auto-convert dimensions.

Broken vs fixed

// BROKEN: index built with one embedding model,
// later queried with another.

import { Settings, VectorStoreIndex } from "llamaindex";
import { OpenAIEmbedding } from "@llamaindex/openai";

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

const index = await VectorStoreIndex.fromDocuments(docs);

// later in another deploy
Settings.embedModel = new OpenAIEmbedding({
  model: "text-embedding-3-large", // 3072 dims
});

const queryEngine = index.asQueryEngine();
const response = await queryEngine.query({ query: "What is our SLA?" });

// FIXED: keep embedding model stable for the lifetime of the index.
// If you change models, rebuild the vector store/index.

import { Settings, VectorStoreIndex } from "llamaindex";
import { OpenAIEmbedding } from "@llamaindex/openai";

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

Settings.embedModel = embedModel;

const index = await VectorStoreIndex.fromDocuments(docs);

const queryEngine = index.asQueryEngine({
  retriever: {
    similarityTopK: 5,
  },
});

const response = await queryEngine.query({ query: "What is our SLA?" });

If you already changed dimensions in production, the fix is not “retry.” You need to either:

• •rebuild the entire index with the new embedding model
• •or create a fresh collection/namespace/table for the new dimension

Other Possible Causes

1) Your vector store schema was created for a different dimension

This happens a lot with pgvector and Qdrant. The table or collection was initialized at 1536, but your current model returns 3072.

// Example: pgvector table created for 1536 dims
await db.query(`
  CREATE TABLE documents (
    id text PRIMARY KEY,
    embedding vector(1536)
  )
`);

If your embedding model now outputs 3072, inserts will fail immediately.

2) Mixed documents from multiple embedding pipelines

You may have one service writing embeddings from OpenAI and another writing embeddings from Cohere or Voyage. Same collection, different dimensions.

// Service A
Settings.embedModel = new OpenAIEmbedding({ model: "text-embedding-3-small" });

// Service B
Settings.embedModel = new SomeOtherEmbeddingModel({
  // returns a different vector length
});

This usually breaks when both services target the same namespace or collection.

3) Cached vectors from an old deployment

Your app code changed, but the database still holds old vectors. This shows up after deploys where you changed env vars like EMBED_MODEL.

# old deploy
EMBED_MODEL=text-embedding-3-small

# new deploy
EMBED_MODEL=text-embedding-3-large

If you didn’t migrate existing data, retrieval will fail on mixed dimensions.

4) Custom embedding wrapper returns inconsistent output

If you wrote your own adapter around an embeddings API, make sure it always returns fixed-length arrays. A bug in post-processing can truncate or pad vectors.

class MyEmbedder {
  async getTextEmbedding(text: string): Promise<number[]> {
    const v = await externalApiEmbed(text);
    return v.slice(0, 1024); // bad if store expects 1536/3072/etc.
  }
}

How to Debug It

1. •

   Print the actual embedding length at runtime.

   Log one sample before insertion and before query.

   const vec = await Settings.embedModel.getTextEmbedding("test");
   console.log("embedding length:", vec.length);
   

   If that number changed since your last deployment, you found it.

2. •

   Check what dimension your vector store expects.

   For pgvector, inspect schema. For Pinecone/Qdrant/Weaviate, inspect index or collection config.

   • •pgvector: vector(1536)
   • •Pinecone: index dimension in dashboard/API
   • •Qdrant: collection vector size
3. •

   Verify every writer uses the same embed config.

   Search for all places that set Settings.embedModel or instantiate an embedder directly.

   If one service uses text-embedding-3-small and another uses text-embedding-3-large, that’s your mismatch.

4. •

   Reproduce with a fresh empty collection.

   If inserts work into a brand-new collection but fail on the old one, your stored schema/data is stale.

   That tells you to rebuild or migrate instead of debugging application logic.

Prevention

• •

  Pin the embedding model explicitly in code and config.

  Don’t rely on defaults across deploys. Treat embedding dimension as part of your schema contract.

• •

  Version your vector indexes.

  If you change models, create a new namespace/collection/table name like docs_v1, docs_v2.

• •

  Add a startup check.

  Fail fast if expectedDimension !== actualDimension before serving traffic.

const sample = await Settings.embedModel.getTextEmbedding("dimension check");
if (sample.length !== EXPECTED_DIMENSION) {
  throw new Error(
    `Embedding dimension mismatch: expected ${EXPECTED_DIMENSION}, got ${sample.length}`
  );
}

If you’re seeing this in production, don’t patch around it at query time. Fix the schema-model contract, rebuild stale vectors, and keep one embedding dimension per index.

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.