run-llama/llama_index · critical · ValueError

Did not find {key}, please add an environment variable `{env

Error message

Did not find {key}, please add an environment variable `{env_key}` which contains it, or pass  `{key}` as a named parameter.

What it means

Raised by get_from_param_or_env when a required value was not supplied as a parameter, not found (or empty) under the given environment variable, and no default was provided. This helper standardizes credential/config resolution across LLM and embedding client constructors (api_key, etc.).

Source

Thrown at llama-index-core/llama_index/core/base/llms/generic_utils.py:325

    return gen()


def get_from_param_or_env(
    key: str,
    param: Optional[str] = None,
    env_key: Optional[str] = None,
    default: Optional[str] = None,
) -> str:
    """Get a value from a param or an environment variable."""
    if param is not None:
        return param
    elif env_key and env_key in os.environ and os.environ[env_key]:
        return os.environ[env_key]
    elif default is not None:
        return default
    else:
        raise ValueError(
            f"Did not find {key}, please add an environment variable"
            f" `{env_key}` which contains it, or pass"
            f"  `{key}` as a named parameter."
        )


def image_node_to_image_block(image_node: ImageNode) -> ImageBlock:
    """
    Get an ImageBlock from an ImageNode.

    Args:
        image_node (ImageNode): ImageNode to convert.

    Returns:
        ImageBlock: block representation of the node.

    Raises:
        ValueError: when the image provided within the ImageNode is not correctly base64-encoded.

View on GitHub (pinned to afd0fef371)

Solutions

Export the expected environment variable with a non-empty value (e.g. export OPENAI_API_KEY=sk-...).
Pass the key directly as a named parameter (api_key=...) at construction.
Verify loading: check os.environ.get('OPENAI_API_KEY') is truthy before constructing the client; ensure your .env loader (python-dotenv) ran and the var name matches exactly.

Example fix

# before
llm = OpenAI(model="gpt-4o")  # OPENAI_API_KEY unset -> ValueError

# after
llm = OpenAI(model="gpt-4o", api_key=os.environ["OPENAI_API_KEY"])
# or: export OPENAI_API_KEY=sk-... in the shell/container

Defensive patterns

Strategy: validation

Validate before calling

import os
api_key = os.environ.get("OPENAI_API_KEY") or os.environ.get("YOUR_PROVIDER_KEY")
if not api_key:
    raise RuntimeError("Missing API key: set OPENAI_API_KEY or pass api_key=")
llm = OpenAI(model="gpt-4o", api_key=api_key)

Try / catch

try:
    client = OpenAI(api_key=api_key)
except ValueError as e:
    if "environment variable" in str(e):
        raise RuntimeError(f"Config error: {e}") from e
    raise

Prevention

Validate required env vars at process startup, not at first LLM call.
Use a secrets manager or .env loader and fail fast with a clear message.
Never assume CI/containers inherit your local env.

When it happens

Trigger: Instantiating a client (e.g. OpenAI-type LLM/embeddings) with api_key=None when the matching env var (e.g. OPENAI_API_KEY) is unset or set to an empty string, and no default passed.

Common situations: Missing/empty environment variable in a new shell, container, or CI; env var name typo; using a non-standard provider whose env key differs (e.g. passing api_base but forgetting api_key for an OpenAI-compatible endpoint); .env file not loaded.

Related errors

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