run-llama/llama_index · error · ValueError

embed_model must start with str 'local' or of type BaseEmbed

Error message

embed_model must start with str 'local' or of type BaseEmbedding

What it means

resolve_embed_model() interprets a string embed_model as a local HuggingFace model only when it starts with 'local' (optionally 'local:<model_name>'). Any other string that is not 'default' or 'clip...' falls through to this branch, fails the is_local check, and raises ValueError — the string shortcut supports exactly three prefixes.

Source

Thrown at llama-index-core/llama_index/core/embeddings/utils.py:102

            )
            embed_model = ClipEmbedding(model_name=clip_model_name)
        except ImportError as e:
            raise ImportError(
                "`llama-index-embeddings-clip` package not found, "
                "please run `pip install llama-index-embeddings-clip` and `pip install git+https://github.com/openai/CLIP.git`"
            )

    if isinstance(embed_model, str):
        try:
            from llama_index.embeddings.huggingface import (
                HuggingFaceEmbedding,
            )  # pants: no-infer-dep

            splits = embed_model.split(":", 1)
            is_local = splits[0]
            model_name = splits[1] if len(splits) > 1 else None
            if is_local != "local":
                raise ValueError(
                    "embed_model must start with str 'local' or of type BaseEmbedding"
                )

            cache_folder = os.path.join(get_cache_dir(), "models")
            os.makedirs(cache_folder, exist_ok=True)

            embed_model = HuggingFaceEmbedding(
                model_name=model_name, cache_folder=cache_folder
            )
        except ImportError:
            raise ImportError(
                "`llama-index-embeddings-huggingface` package not found, "
                "please run `pip install llama-index-embeddings-huggingface`"
            )

    if LCEmbeddings is not None and isinstance(embed_model, LCEmbeddings):
        try:
            from llama_index.embeddings.langchain import (

View on GitHub (pinned to afd0fef371)

Solutions

Prefix the model id with 'local:': embed_model='local:BAAI/bge-small-en-v1.5'
Or pass a real instance: HuggingFaceEmbedding(model_name='BAAI/bge-small-en-v1.5') (requires llama-index-embeddings-huggingface)
Remember the other accepted strings are only 'default' (OpenAI) and 'clip[:model]'

Example fix

// before
index = VectorStoreIndex.from_documents(docs, embed_model="BAAI/bge-small-en-v1.5")
# ValueError

// after
index = VectorStoreIndex.from_documents(
    docs, embed_model="local:BAAI/bge-small-en-v1.5"
)

Defensive patterns

Strategy: validation

Validate before calling

if isinstance(embed_model, str) and embed_model not in ("default",) and not embed_model.startswith(("local", "clip")):
    embed_model = f"local:{embed_model}"  # normalize raw HF model ids

Type guard

def is_valid_embed_str(s: str) -> bool:
    return s == "default" or s.startswith("local") or s.startswith("clip")

Prevention

Remember the accepted string forms: 'default', 'clip[:model]', 'local[:model]'
Validate embed_model strings at config load time with a startup check
Prefer passing BaseEmbedding instances in application code to avoid string-grammar pitfalls

When it happens

Trigger: Passing a raw model id like embed_model='BAAI/bge-small-en-v1.5' or embed_model='sentence-transformers/all-MiniLM-L6-v2' instead of 'local:BAAI/bge-small-en-v1.5'; passing 'LOCAL:model' (case-sensitive) or 'huggingface:model'.

Common situations: Copy-pasting a HuggingFace model id from the hub directly into embed_model; assuming any model name resolves; case or separator typos ('local:' vs 'local=', 'locale:').

Related errors

AI-assisted analysis of run-llama/llama_index@afd0fef371 (2026-08-15). Data as JSON: /api/errors/2671379856fd7a3c. Report an issue: GitHub.