What causes "Required environment variable {key!r} is not set" in calesthio/OpenMontage?

Create/extend the project .env file with the missing key and rerun.

calesthio/OpenMontage · error · EnvironmentError

Required environment variable {key!r} is not set

Error message

Required environment variable {key!r} is not set

What it means

Raised by lib/env_loader.py's require_env() when os.environ does not contain the requested key. require_env is the strict variant of get_env: get_env returns a default, require_env raises EnvironmentError so startup fails fast instead of passing None into downstream code. It is the standard way OpenMontage enforces that provider keys (API keys, tokens) exist before any paid or network call is made.

Source

Thrown at lib/env_loader.py:33

def load_env(project_root: Optional[Path] = None) -> None:
    """Load .env file from project root."""
    if project_root is None:
        project_root = Path(__file__).resolve().parent.parent
    env_path = project_root / ".env"
    if env_path.exists():
        load_dotenv(env_path)


def get_env(key: str, default: Optional[str] = None) -> Optional[str]:
    """Get an environment variable with optional default."""
    return os.environ.get(key, default)


def require_env(key: str) -> str:
    """Get a required environment variable. Raises if missing."""
    value = os.environ.get(key)
    if value is None:
        raise EnvironmentError(f"Required environment variable {key!r} is not set")
    return value

View on GitHub (pinned to 95e1c3d0ab)

Solutions

Create/extend the project .env file with the missing key and rerun.
Verify load_dotenv(env_path) is called with the correct path before require_env, and that the file is named/located as expected.
Export the variable in the shell or CI environment (export KEY=value) if .env is not used.
If the key is optional for your flow, use get_env(key, default) instead of require_env.

Example fix

# before
key = require_env("ATLASCLOUD_API_KEY")  # raises if unset

# after
from lib.env_loader import load_dotenv, get_env, require_env
load_dotenv(PROJECT_DIR / ".env")  # ensure .env is loaded first
key = require_env("ATLASCLOUD_API_KEY")

Defensive patterns

Strategy: validation

Validate before calling

import os
from lib.env_loader import get_env

missing = [k for k in REQUIRED_KEYS if not get_env(k)]
if missing:
    raise SystemExit(f"Missing env vars: {', '.join(missing)}")

Type guard

def env_is_set(key: str) -> bool:
    return bool(os.environ.get(key))

Try / catch

try:
    api_key = require_env("ATLASCLOUD_API_KEY")
except EnvironmentError as e:
    raise SystemExit(f"Startup blocked: {e}. Add it to .env and rerun.") from e

Prevention

Call load_dotenv with an explicit, correct env_path at process start.
Validate all required keys in one preflight loop before any work begins.
Keep a checked-in .env.example listing every key require_env consumes.
Prefer get_env with defaults for optional keys; reserve require_env for true hard dependencies.

When it happens

Trigger: Calling require_env('ATLASCLOUD_API_KEY') (or any other key) when the variable is unset — e.g. no .env file at the expected env_path, load_dotenv pointed at the wrong file, or the process launched from an environment that never exported the variable.

Common situations: Fresh clone without a .env; CI runner missing secret configuration; variable name typo or renamed key after a version upgrade; .env present but load_dotenv was never called or was called with an incorrect path.

Related errors

AI-assisted analysis of calesthio/OpenMontage@95e1c3d0ab (2026-08-15). Data as JSON: /api/errors/e8da752ef300dc42. Report an issue: GitHub.