# ValueError: Embedding dimension mismatch: query embedding dimension (384) does not match index embedding dimension (768)

- **ID:** `llm/llamaindex-embedding-model-mismatch-on-retrieval`
- **Domain:** llm
- **Category:** config_error
- **Verification:** ai_generated
- **Fix Rate:** 90%

## Root Cause

LlamaIndex retrieves a query using an embedding model with a different output dimension than the model used to build the vector index, often due to changing the embed_model config after index construction.

## Version Compatibility

| Version | Status | Introduced | Deprecated |
|---------|--------|------------|------------|
| llama-index 0.10.0 | active | — | — |
| llama-index 0.10.15 | active | — | — |
| llama-index 0.10.30 | active | — | — |
| sentence-transformers 2.2.2 | active | — | — |
| sentence-transformers 3.0.0 | active | — | — |

## Workarounds

1. **Rebuild the index with the same embedding model used for queries:

from llama_index.core import VectorStoreIndex, Settings
from llama_index.embeddings.huggingface import HuggingFaceEmbedding

embed_model = HuggingFaceEmbedding(model_name='BAAI/bge-small-en-v1.5')
Settings.embed_model = embed_model
index = VectorStoreIndex.from_documents(documents, embed_model=embed_model)** (95% success)
   ```
   Rebuild the index with the same embedding model used for queries:

from llama_index.core import VectorStoreIndex, Settings
from llama_index.embeddings.huggingface import HuggingFaceEmbedding

embed_model = HuggingFaceEmbedding(model_name='BAAI/bge-small-en-v1.5')
Settings.embed_model = embed_model
index = VectorStoreIndex.from_documents(documents, embed_model=embed_model)
   ```
2. **Persist the embedding model name in index metadata and validate on load:

from llama_index.core import StorageContext, load_index_from_storage

storage_context = StorageContext.from_defaults(persist_dir='./index')
index = load_index_from_storage(storage_context)
if index.embed_model != current_embed_model:
    raise ValueError(f"Embed model mismatch: index uses {index.embed_model}")** (90% success)
   ```
   Persist the embedding model name in index metadata and validate on load:

from llama_index.core import StorageContext, load_index_from_storage

storage_context = StorageContext.from_defaults(persist_dir='./index')
index = load_index_from_storage(storage_context)
if index.embed_model != current_embed_model:
    raise ValueError(f"Embed model mismatch: index uses {index.embed_model}")
   ```

## Dead Ends

- **** — Reshaping distorts the embedding space, producing semantically meaningless similarity scores and retrieval results. (80% fail)
- **** — The default embedding model may still have a different dimension than the one used during indexing, unless it's the exact same model. (50% fail)