run-llama/llama_index · critical · ValueError

****** Could not load OpenAI embedding model. If you intend

Error message

******
Could not load OpenAI embedding model. If you intended to use OpenAI, please check your OPENAI_API_KEY.
Original error:
{e!s}
Consider using embed_model='local'.
Visit our documentation for more embedding options: https://developers.llamaindex.ai/python/framework/module_guides/models/embeddings/
******

What it means

While building the default OpenAI embedding, validate_openai_api_key() raised a ValueError (typically 'No API key found' or 'Incorrect API key provided') which resolve_embed_model() re-raises with remediation text. The OpenAI integration IS installed; the OPENAI_API_KEY is missing, empty, or rejected by the API.

Source

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

        try:
            from llama_index.embeddings.openai import (
                OpenAIEmbedding,
            )  # pants: no-infer-dep

            from llama_index.embeddings.openai.utils import (
                validate_openai_api_key,
            )  # pants: no-infer-dep

            embed_model = OpenAIEmbedding()
            validate_openai_api_key(embed_model.api_key)  # type: ignore
        except ImportError:
            raise ImportError(
                "`llama-index-embeddings-openai` package not found, "
                "please run `pip install llama-index-embeddings-openai`"
            )
        except ValueError as e:
            raise ValueError(
                "\n******\n"
                "Could not load OpenAI embedding model. "
                "If you intended to use OpenAI, please check your OPENAI_API_KEY.\n"
                "Original error:\n"
                f"{e!s}"
                "\nConsider using embed_model='local'.\n"
                "Visit our documentation for more embedding options: "
                "https://developers.llamaindex.ai/python/framework/module_guides/"
                "models/embeddings/"
                "\n******"
            )
    # for image multi-modal embeddings
    elif isinstance(embed_model, str) and embed_model.startswith("clip"):
        try:
            from llama_index.embeddings.clip import ClipEmbedding  # pants: no-infer-dep

            clip_model_name = (
                embed_model.split(":")[1] if ":" in embed_model else "ViT-B/32"

View on GitHub (pinned to afd0fef371)

Solutions

Set a valid key: export OPENAI_API_KEY=sk-... and verify with a direct OpenAI call
If you never intended OpenAI, pass embed_model='local:<model>' (HuggingFace) or any BaseEmbedding instance explicitly
Load .env before llama-index imports/usage (from dotenv import load_dotenv; load_dotenv())

Example fix

// before
index = VectorStoreIndex.from_documents(docs)  # no OPENAI_API_KEY set

// after
export OPENAI_API_KEY=sk-...
index = VectorStoreIndex.from_documents(docs)
# or fully local:
index = VectorStoreIndex.from_documents(
    docs, embed_model="local:BAAI/bge-small-en-v1.5"
)

Defensive patterns

Strategy: validation

Validate before calling

import os
if embed_model in (None, "default") and not os.environ.get("OPENAI_API_KEY"):
    raise RuntimeError("OPENAI_API_KEY not set; set it or pass embed_model='local:...'")

Try / catch

try:
    index = VectorStoreIndex.from_documents(docs)
except ValueError as e:
    if "OPENAI_API_KEY" in str(e):
        raise RuntimeError("missing/invalid OpenAI key; export OPENAI_API_KEY or use local embeddings") from e
    raise

Prevention

Call load_dotenv() before any llama-index Settings/index usage
Smoke-test the key at startup with a one-token embeddings request
Default to 'local:' embeddings in offline deployments so no key is needed

When it happens

Trigger: Constructing an index without embed_model while OPENAI_API_KEY is unset, set to an invalid/revoked key, or uses wrong env var name; key loaded too late (dotenv imported after llama-index call); a placeholder key like 'sk-...' in a template .env.

Common situations: Forgetting export OPENAI_API_KEY in shell/CI/Docker; rotated or revoked keys; copy-pasting example code without setting the env var; .env not loaded before Settings resolution.

Related errors

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