run-llama/llama_index · error · ValueError

****** Could not load OpenAI model. If you intended to use

Error message

******
Could not load OpenAI model. If you intended to use OpenAI, please check your OPENAI_API_KEY.
Original error:
{e}
******

What it means

During default-LLM resolution, llama-index constructs OpenAI() and calls validate_openai_api_key; if that raises (missing/invalid OPENAI_API_KEY), the ValueError is re-raised wrapped in a prominent message telling you to check the key. It exists so a missing key surfaces immediately at setup rather than as an opaque 401 later.

Source

Thrown at llama-index-core/llama_index/core/llms/utils.py:64

            llm.callback_manager = callback_manager or Settings.callback_manager
            return llm

        # return default OpenAI model. If it fails, return LlamaCPP
        try:
            from llama_index.llms.openai import OpenAI  # pants: no-infer-dep
            from llama_index.llms.openai.utils import (
                validate_openai_api_key,
            )  # pants: no-infer-dep

            llm = OpenAI()
            validate_openai_api_key(llm.api_key)  # type: ignore
        except ImportError:
            raise ImportError(
                "`llama-index-llms-openai` package not found, "
                "please run `pip install llama-index-llms-openai`"
            )
        except ValueError as e:
            raise ValueError(
                "\n******\n"
                "Could not load OpenAI model. "
                "If you intended to use OpenAI, please check your OPENAI_API_KEY.\n"
                "Original error:\n"
                f"{e!s}"
                "\n******"
            )

    if isinstance(llm, str):
        splits = llm.split(":", 1)
        is_local = splits[0]
        model_path = splits[1] if len(splits) > 1 else None
        if is_local != "local":
            raise ValueError(
                "llm must start with str 'local' or of type LLM or BaseLanguageModel"
            )
        try:
            from llama_index.llms.llama_cpp.llama_utils import (

View on GitHub (pinned to afd0fef371)

Solutions

Set a valid key: export OPENAI_API_KEY=sk-... (or wire it via your env/secret manager) and confirm with print(os.environ.get('OPENAI_API_KEY')).
If the key is fine but you don't want OpenAI, pass an explicit LLM: Settings.llm = <installed LLM>().
Verify the key with a minimal OpenAI API call or validate_openai_api_key to separate key issues from code issues.
Check that a custom base_url/proxy in the environment accepts this key.

Example fix

# before
# OPENAI_API_KEY unset -> ValueError on first index/query call
# after
import os
os.environ["OPENAI_API_KEY"] = "sk-..."  # or export in shell
# or bypass the default entirely
from llama_index.core.llms.mock import MockLLM
Settings.llm = MockLLM()

Defensive patterns

Strategy: validation

Validate before calling

import os

def openai_key_present() -> bool:
    return bool(os.environ.get("OPENAI_API_KEY", "").strip())

assert openai_key_present(), "OPENAI_API_KEY must be set before creating indexes"

Try / catch

try:
    Settings.llm = OpenAI()
except ValueError as e:
    if "OPENAI_API_KEY" in str(e):
        raise SystemExit("Set OPENAI_API_KEY in the environment") from e
    raise

Prevention

Load .env files explicitly (python-dotenv) at process start.
Set an explicit Settings.llm in offline/test environments (e.g. MockLLM).
Validate the key's presence in a startup health check, not on first query.

When it happens

Trigger: Any implicit default-LLM resolution (no llm passed) in a process where OPENAI_API_KEY is unset, empty, malformed, or revoked, or where the key belongs to an incompatible endpoint/base_url.

Common situations: Env var not exported in the shell/venv/Docker/compose/cron; .env file not loaded; key rotated or revoked; CI secrets not wired; OPENAI_API_BASE_URL mismatched with the key type.

Related errors

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