{"record":{"id":"c24bccb709fff5e3","repo":"cocoindex-io/cocoindex","slug":"env-name-is-not-set","errorCode":null,"errorMessage":"{env_name} is not set","messagePattern":"(.+?) is not set","errorType":"validation","errorClass":"ValueError","httpStatus":null,"severity":"error","filePath":"python/cocoindex/_internal/setting.py","lineNumber":45,"sourceCode":"    `map_size` is the *initial* size of the LMDB memory map, not a cap: the\n    engine doubles the map and retries whenever a write runs out of space.\n    \"\"\"\n\n    max_dbs: int = 1024\n    map_size: int = 0x1_0000_0000  # 4 GiB\n\n\ndef _load_field(\n    target: dict[str, Any],\n    name: str,\n    env_name: str,\n    required: bool = False,\n    parse: Callable[[str], Any] | None = None,\n) -> None:\n    value = os.getenv(env_name)\n    if value is None:\n        if required:\n            raise ValueError(f\"{env_name} is not set\")\n    else:\n        if parse is None:\n            target[name] = value\n        else:\n            try:\n                target[name] = parse(value)\n            except Exception as e:\n                raise ValueError(\n                    f\"failed to parse environment variable {env_name}: {value}\"\n                ) from e\n\n\n@dataclass(init=False)\nclass Settings:\n    \"\"\"Settings for the cocoindex library.\"\"\"\n\n    db_path: os.PathLike[str] | None\n    db_settings: LmdbSettings","sourceCodeStart":27,"sourceCodeEnd":63,"githubUrl":"https://github.com/cocoindex-io/cocoindex/blob/e84aa99b3292c5270a4b313b2a7137ad9ce8ab3b/python/cocoindex/_internal/setting.py#L27-L63","documentation":"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.","triggerScenarios":"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.","commonSituations":"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.","solutions":["Set the missing environment variable before running (export COCOINDEX_...=... or add it to .env/shell profile)","Check the variable name spelling against the name expected by the settings loader","In containers/CI, add the variable to the deployment secrets/env configuration","If the field should truly be optional, pass a default instead of required=True in settings code"],"exampleFix":"// before\n# DATABASE_URL not set; from_env() raises\nsettings = Settings.from_env()\n// after\nexport DATABASE_URL=postgresql://localhost:5432/mydb\nsettings = Settings.from_env()","handlingStrategy":"validation","validationCode":"import os\nmissing = [k for k in (\"COCOINDEX_DATABASE_URL\",) if not os.getenv(k)]\nif missing:\n    raise SystemExit(f\"missing env vars: {missing}\")","typeGuard":"def env_set(name: str) -> bool:\n    return os.getenv(name) is not None","tryCatchPattern":"try:\n    settings = Settings.from_env()\nexcept ValueError as e:\n    print(f\"configuration error: {e}; set the required env var and retry\")\n    sys.exit(1)","preventionTips":["Use a checked-in .env.example listing all required vars","Validate env vars at process startup, not deep in runtime","Use consistent naming for env vars and double-check spelling"],"tags":["environment","configuration","env-var"],"backgroundTag":"missing-env-var","analyzedSha":"e84aa99b3292c5270a4b313b2a7137ad9ce8ab3b","analyzedAt":"2026-09-08T15:59:19.997Z","contentChangedAt":"2026-09-08T15:59:19.997Z","schemaVersion":2},"datasetVersion":"2026-09-14T05:17:10.506Z"}