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

This error means your vector store already contains embeddings of one size, but your current embedding model is producing a different size. In LlamaIndex TypeScript, it usually shows up when you switch models, reuse an old index, or point a new app version at an existing persisted collection.

The failure is not in retrieval logic. It happens earlier, when LlamaIndex tries to insert or query vectors and the underlying store rejects the dimension mismatch.

The Most Common Cause

The #1 cause is changing the embedding model after the index was already created.

If you built the index with one model and later load the same persisted store with another model, you’ll hit errors like:

• •Error: Vector dimension mismatch
• •Expected vector of dimension 1536, got 3072
• •PineconeBadRequest: Vector dimension 1536 does not match the dimension of the index 3072
• •Qdrant error: expected dim 1536, got 3072

Here’s the broken pattern.

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

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

const storageContext = await storageContextFromDefaults({
  persistDir: "./storage",
});

// This directory may contain vectors created with text-embedding-3-small (1536 dims)
const index = await VectorStoreIndex.init({
  storageContext,
  embedModel,
});

// Later: query or insert triggers
// Error: Expected vector of dimension 1536, got 3072

// FIXED OPTION 1: Use the same embedding model that created the stored index
import { VectorStoreIndex, storageContextFromDefaults } from "llamaindex";
import { OpenAIEmbedding } from "@llamaindex/openai";

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

const storageContext = await storageContextFromDefaults({
  persistDir: "./storage",
});

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

// FIXED OPTION 2: Rebuild the index if you want to change models
import {
  Document,
  VectorStoreIndex,
} from "llamaindex";
import { OpenAIEmbedding } from "@llamaindex/openai";

const docs = [
  new Document({ text: "Fresh rebuild with a new embedding model." }),
];

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

const index = await VectorStoreIndex.fromDocuments(docs, {
  embedModel,
});

// Persist this as a new collection / directory name

If you changed models, do not point at old persisted data and expect it to work. Embedding dimensions are part of your schema.

Other Possible Causes

1. Your vector database collection was created with a different dimension

This happens a lot with Pinecone and Qdrant. The collection/index was created once, then reused later with a different embedding model.

// Pinecone example: collection/index must match embedding dim exactly
// If your embeddings are 1536-dim, create Pinecone with dimension: 1536

await pinecone.createIndex({
  name: "my-index",
  dimension: 1536,
});

If you switch to text-embedding-3-large, that same index will break unless you recreate it with dimension: 3072.

2. You mixed embedding providers in the same app

One part of your code uses OpenAI embeddings, another uses Cohere or Hugging Face. The store only sees raw vectors; it does not care that they came from different providers.

// Broken: ingest uses one provider, query uses another
const ingestEmbedModel = new OpenAIEmbedding({ model: "text-embedding-3-small" });
const queryEmbedModel = new CohereEmbedding({ model: "embed-english-v3.0" });

Keep ingestion and querying on the same embedding class and model unless you have explicitly designed for separate indexes.

3. You changed models between environments

Local dev may use one .env, staging another. The code looks identical, but one environment points to a different default embedding config.

# .env.local
EMBED_MODEL=text-embedding-3-small

# .env.staging
EMBED_MODEL=text-embedding-3-large

If both environments share the same persisted store or remote vector DB collection, one of them will fail.

4. You are loading stale persisted data after changing chunking or schema assumptions

Chunking itself does not change vector dimension, but it often travels with a refactor where you also swapped models. That makes debugging messy because the failure appears after ingestion changes.

// After refactor:
// - new chunking strategy
// - new embedding model
// - old persisted directory still mounted

await storageContextFromDefaults({ persistDir: "./storage" });

If you changed embedding config, treat old stored vectors as invalid unless proven otherwise.

How to Debug It

1. •

   Print the active embedding model at runtime

   • •Log the exact provider and model name before indexing and querying.
   • •Example:

     console.log("Embedding model:", embedModel);
     

2. •

   Check what dimension your current model produces

   • •OpenAI:
     • •text-embedding-3-small → 1536
     • •text-embedding-3-large → 3072
   • •Compare that against your vector DB index/collection settings.
3. •

   Inspect the existing store

   • •For Pinecone, check the index dimension in the dashboard or via API.
   • •For Qdrant/Weaviate/Chroma, inspect collection schema or recreate it cleanly if needed.
4. •

   Delete and rebuild once

   • •If you suspect stale data, wipe the local persist directory or create a fresh remote collection.
   • •If the error disappears, your issue was mismatched historical vectors.

A simple rule helps here:

Prevention

• •Pin your embedding model in code and config.
  • •Do not rely on defaults if you persist indexes across deployments.
• •Version your vector collections by embedding schema.
  • •Example: docs_v1_1536, docs_v2_3072.
• •Rebuild indexes whenever you change:
  • •embedding provider
  • •embedding model name
  • •vector DB collection dimension

If you want this class of bug to stay dead, make “embedding schema” part of your deployment checklist. One silent model swap is enough to break retrieval across an entire app.

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.