{"record":{"id":"5bb876b1e556e749","repo":"cocoindex-io/cocoindex","slug":"failed-to-parse-environment-variable-env-name","errorCode":null,"errorMessage":"failed to parse environment variable {env_name}: {value}","messagePattern":"failed to parse environment variable (.+?): (.+?)","errorType":"validation","errorClass":"ValueError","httpStatus":null,"severity":"error","filePath":"python/cocoindex/_internal/setting.py","lineNumber":53,"sourceCode":"def _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\n    # Deprecated v0 leftover; has no effect in v1. Kept (always `None`) so callers\n    # that still pass `global_execution_options=None` don't break.\n    global_execution_options: None\n\n    def __init__(\n        self,\n        db_path: os.PathLike[str] | None = None,\n        db_settings: LmdbSettings | None = None,","sourceCodeStart":35,"sourceCodeEnd":71,"githubUrl":"https://github.com/cocoindex-io/cocoindex/blob/e84aa99b3292c5270a4b313b2a7137ad9ce8ab3b/python/cocoindex/_internal/setting.py#L35-L71","documentation":"When an environment variable is present but fails its registered parse function (e.g. an int/bool/Dsn parser), _load_field wraps the parser exception in this ValueError so the offending variable name and raw value are visible. It means the value's format, not its presence, is wrong.","triggerScenarios":"Calling from_env() where an env var exists but its value cannot be parsed — e.g. COCOINDEX_LMDB_MAP_SIZE=\"abc\" for an int field, or a malformed URL/DSN passed to a DSN parser.","commonSituations":"Quoted or whitespace-polluted values in .env files ('123' with literal quotes); pasting values with trailing newlines; using non-numeric sizes for int settings; typos in URLs.","solutions":["Fix the env var value to match the expected format (e.g. plain integer bytes for size fields)","Remove stray quotes, spaces, or trailing characters from the .env entry","Test the value against the parse function implied by the field (int(), Dsn parsing, etc.)","Check for shell interpolation issues that mangled the value"],"exampleFix":"// before\nCOCOINDEX_LMDB_MAP_SIZE=\"1gb\"   # fails int parse\n// after\nCOCOINDEX_LMDB_MAP_SIZE=1073741824","handlingStrategy":"validation","validationCode":"raw = os.getenv(\"COCOINDEX_LMDB_MAP_SIZE\", \"\")\nif raw and not raw.strip().lstrip(\"+-\").isdigit():\n    raise SystemExit(f\"COCOINDEX_LMDB_MAP_SIZE must be an int, got {raw!r}\")","typeGuard":null,"tryCatchPattern":"try:\n    settings = Settings.from_env()\nexcept ValueError as e:\n    print(e)  # names the env var and offending value\n    fix_env_and_retry()","preventionTips":["Avoid quotes and whitespace around values in .env files","Echo/print env values when debugging configuration","Keep values in the exact format the parser expects (plain ints, plain URLs)"],"tags":["environment","configuration","parsing"],"backgroundTag":"invalid-env-var-value","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"}