What causes "MORPH_API_KEY environment variable is required" in huggingface/open-r1?

Add MORPH_API_KEY= to a .env file in the working directory where the script is launched.

MORPH_API_KEY environment variable is required

Error message

MORPH_API_KEY environment variable is required

What it means

After confirming MorphCloud is importable, get_morph_client_from_env loads .env and reads MORPH_API_KEY. If the variable is unset or empty it raises ValueError, because constructing MorphCloudExecutionClient requires a valid API key for MorphCloud's API.

Source

Thrown at src/open_r1/utils/competitive_programming/morph_client.py:737

    Environment variables:
        MORPH_API_KEY: API key for MorphCloud

    Args:
        session: Optional aiohttp.ClientSession to use for HTTP requests

    Returns:
        MorphCloudExecutionClient: A configured MorphCloud execution client
    """
    if not is_morph_available():
        raise ImportError(
            "MorphCloud is not available and required for this function. Please install MorphCloud with "
            "`pip install morphcloud` and add an API key to a `.env` file."
        )

    load_dotenv()
    api_key = os.environ.get("MORPH_API_KEY")
    if not api_key:
        raise ValueError("MORPH_API_KEY environment variable is required")

    return MorphCloudExecutionClient(api_key=api_key)


# noqa: W293

View on GitHub (pinned to 1416fa0cf2)

Solutions

Add MORPH_API_KEY=<your key> to a .env file in the working directory where the script is launched.
Or export MORPH_API_KEY in the shell/environment running the reward pipeline.
Verify with python -c "import os; from dotenv import load_dotenv; load_dotenv(); print(os.environ.get('MORPH_API_KEY'))".
In CI, ensure the secret is injected into the job environment under the exact name MORPH_API_KEY.

Example fix

// before
$ python reward.py  # ValueError: MORPH_API_KEY required
// after
$ echo 'MORPH_API_KEY=morph_...' >> .env && python reward.py

Defensive patterns

Strategy: validation

Validate before calling

import os
from dotenv import load_dotenv
load_dotenv()
assert os.environ.get('MORPH_API_KEY'), 'MORPH_API_KEY missing: add it to .env or export it'

Type guard

def morph_key_present() -> bool:
    return bool(os.environ.get('MORPH_API_KEY'))

Try / catch

try:
    client = get_morph_client_from_env()
except ValueError as e:
    if 'MORPH_API_KEY' in str(e):
        raise SystemExit('Set MORPH_API_KEY in .env before running IOI rewards') from e
    raise

Prevention

Keep a .env.example with MORPH_API_KEY documented
Load .env from the script's launch directory (cwd matters for load_dotenv)
Inject the secret by its exact name in CI/cluster environments
Validate required env vars in an entrypoint script before starting training

When it happens

Trigger: Calling get_morph_client_from_env (via ioi_code_reward with the morph backend) when the MORPH_API_KEY environment variable is not set — no .env file present, .env not in the process working directory, or the variable named incorrectly (e.g. MORPH_TOKEN).

Common situations: Forgot to create .env; .env exists but in a different directory than where the script runs; exporting the variable in a shell session that didn't propagate (e.g. systemd, CI secrets not injected); typo in variable name.

Understand the failure class

Background: "environment variable is not set" and "Missing keys in environment" errors: what missing required env var messages mean and how to fix them — this error's family across 28 libraries.

Related errors

AI-assisted analysis of huggingface/open-r1@1416fa0cf2 (2026-08-30). Data as JSON: /api/errors/7993e3578a7e57a7. Report an issue: GitHub.