{"record":{"id":"2671379856fd7a3c","repo":"run-llama/llama_index","slug":"embed-model-must-start-with-str-local-or-of-type","errorCode":null,"errorMessage":"embed_model must start with str 'local' or of type BaseEmbedding","messagePattern":"embed_model must start with str 'local' or of type BaseEmbedding","errorType":"exception","errorClass":"ValueError","httpStatus":null,"severity":"error","filePath":"llama-index-core/llama_index/core/embeddings/utils.py","lineNumber":102,"sourceCode":"            )\n            embed_model = ClipEmbedding(model_name=clip_model_name)\n        except ImportError as e:\n            raise ImportError(\n                \"`llama-index-embeddings-clip` package not found, \"\n                \"please run `pip install llama-index-embeddings-clip` and `pip install git+https://github.com/openai/CLIP.git`\"\n            )\n\n    if isinstance(embed_model, str):\n        try:\n            from llama_index.embeddings.huggingface import (\n                HuggingFaceEmbedding,\n            )  # pants: no-infer-dep\n\n            splits = embed_model.split(\":\", 1)\n            is_local = splits[0]\n            model_name = splits[1] if len(splits) > 1 else None\n            if is_local != \"local\":\n                raise ValueError(\n                    \"embed_model must start with str 'local' or of type BaseEmbedding\"\n                )\n\n            cache_folder = os.path.join(get_cache_dir(), \"models\")\n            os.makedirs(cache_folder, exist_ok=True)\n\n            embed_model = HuggingFaceEmbedding(\n                model_name=model_name, cache_folder=cache_folder\n            )\n        except ImportError:\n            raise ImportError(\n                \"`llama-index-embeddings-huggingface` package not found, \"\n                \"please run `pip install llama-index-embeddings-huggingface`\"\n            )\n\n    if LCEmbeddings is not None and isinstance(embed_model, LCEmbeddings):\n        try:\n            from llama_index.embeddings.langchain import (","sourceCodeStart":84,"sourceCodeEnd":120,"githubUrl":"https://github.com/run-llama/llama_index/blob/afd0fef371831f9bda13e5af7167cf4e981278ab/llama-index-core/llama_index/core/embeddings/utils.py#L84-L120","documentation":"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.","triggerScenarios":"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'.","commonSituations":"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:').","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]'"],"exampleFix":"// before\nindex = VectorStoreIndex.from_documents(docs, embed_model=\"BAAI/bge-small-en-v1.5\")\n# ValueError\n\n// after\nindex = VectorStoreIndex.from_documents(\n    docs, embed_model=\"local:BAAI/bge-small-en-v1.5\"\n)","handlingStrategy":"validation","validationCode":"if isinstance(embed_model, str) and embed_model not in (\"default\",) and not embed_model.startswith((\"local\", \"clip\")):\n    embed_model = f\"local:{embed_model}\"  # normalize raw HF model ids","typeGuard":"def is_valid_embed_str(s: str) -> bool:\n    return s == \"default\" or s.startswith(\"local\") or s.startswith(\"clip\")","tryCatchPattern":null,"preventionTips":["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"],"tags":["embeddings","configuration","huggingface","api-misuse"],"backgroundTag":null,"analyzedSha":"afd0fef371831f9bda13e5af7167cf4e981278ab","analyzedAt":"2026-08-15T05:42:58.429Z","schemaVersion":2},"datasetVersion":"2026-08-15T22:17:37.221Z"}