cocoindex-io/cocoindex · error · ValueError

{env_name} is not set

Error message

{env_name} is not set

What it means

Settings loading (from_env) raises this ValueError when a field marked required=True has no corresponding environment variable set. It is a fail-fast guard so the app never runs with missing mandatory configuration.

Source

Thrown at python/cocoindex/_internal/setting.py:45

    `map_size` is the *initial* size of the LMDB memory map, not a cap: the
    engine doubles the map and retries whenever a write runs out of space.
    """

    max_dbs: int = 1024
    map_size: int = 0x1_0000_0000  # 4 GiB


def _load_field(
    target: dict[str, Any],
    name: str,
    env_name: str,
    required: bool = False,
    parse: Callable[[str], Any] | None = None,
) -> None:
    value = os.getenv(env_name)
    if value is None:
        if required:
            raise ValueError(f"{env_name} is not set")
    else:
        if parse is None:
            target[name] = value
        else:
            try:
                target[name] = parse(value)
            except Exception as e:
                raise ValueError(
                    f"failed to parse environment variable {env_name}: {value}"
                ) from e


@dataclass(init=False)
class Settings:
    """Settings for the cocoindex library."""

    db_path: os.PathLike[str] | None
    db_settings: LmdbSettings

View on GitHub (pinned to e84aa99b32)

Solutions

1. Set the missing environment variable before running (export COCOINDEX_...=... or add it to .env/shell profile)
2. Check the variable name spelling against the name expected by the settings loader
3. In containers/CI, add the variable to the deployment secrets/env configuration
4. If the field should truly be optional, pass a default instead of required=True in settings code

Example fix

// before
# DATABASE_URL not set; from_env() raises
settings = Settings.from_env()
// after
export DATABASE_URL=postgresql://localhost:5432/mydb
settings = Settings.from_env()

import os
missing = [k for k in ("COCOINDEX_DATABASE_URL",) if not os.getenv(k)]
if missing:
    raise SystemExit(f"missing env vars: {missing}")

def env_set(name: str) -> bool:
    return os.getenv(name) is not None

try:
    settings = Settings.from_env()
except ValueError as e:
    print(f"configuration error: {e}; set the required env var and retry")
    sys.exit(1)

When it happens

Trigger: Calling Settings.from_env() (or a function that uses it) while an env var declared with _load_field(..., required=True) — e.g. a database DSN or API key — is unset in the environment.

Common situations: Deploying without a .env file loaded; forgetting to export the variable in CI/containers; typo in the env var name; running `cocoindex` CLI before configuring DATABASE_URL-style settings.

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

• Environment settings must provide Settings.db_path (or set C
• failed to parse environment variable {env_name}: {value}
• An app named '{name}' is already registered in this environm
• Settings.db_path must be provided
• Specify either `db_settings=` or the legacy `lmdb_max_dbs=`/

AI-assisted analysis of cocoindex-io/cocoindex@e84aa99b32 (2026-09-08). Data as JSON: /api/errors/c24bccb709fff5e3. Report an issue: GitHub.