{"record":{"id":"c05e1be3b60a7faa","repo":"google-gemini/gemini-cli","slug":"missing-required-environment-variable-name-pl","errorCode":null,"errorMessage":"Missing required environment variable '{name}'. Please ensure your .env file or environment is properly configured.","messagePattern":"Missing required environment variable '(.+?)'\\. Please ensure your \\.env file or environment is properly configured\\.","errorType":"exception","errorClass":"RuntimeError","httpStatus":null,"severity":"critical","filePath":"tools/caretaker-agent/evals/triage/helpers/dataset.py","lineNumber":15,"sourceCode":"\"\"\"Firestore Golden Dataset Streaming\"\"\"\n\nimport os\nfrom typing import Dict, List, Any, Optional\nfrom dotenv import load_dotenv\nfrom google.cloud import firestore\n\nload_dotenv()\n\n\ndef get_env_var(name: str) -> str:\n    \"\"\"Helper that loads an environment variable and fails fast if missing.\"\"\"\n    val = os.environ.get(name)\n    if not val:\n        raise RuntimeError(\n            f\"Missing required environment variable '{name}'. \"\n            f\"Please ensure your .env file or environment is properly configured.\"\n        )\n    return val\n\n\ndef load_issues(filter_issues: Optional[List[int]] = None) -> List[Dict[str, Any]]:\n    \"\"\"Loads golden issue test cases directly from Firestore into memory.\"\"\"\n    project_id = get_env_var(\"PROJECT_ID\")\n    db_id = get_env_var(\"FIRESTORE_DATABASE\")\n    collection_name = get_env_var(\"FIRESTORE_EVAL_COLLECTION\")\n\n    db = firestore.Client(project=project_id, database=db_id)\n    docs = db.collection(collection_name).stream()\n\n    issues = []\n    for doc in docs:\n        data = doc.to_dict()","sourceCodeStart":1,"sourceCodeEnd":33,"githubUrl":"https://github.com/google-gemini/gemini-cli/blob/5024443c7217464a66e98f80d73172a26440bd8f/tools/caretaker-agent/evals/triage/helpers/dataset.py#L1-L33","documentation":"This RuntimeError is raised by get_env_var() in dataset.py when one of the required environment variables (PROJECT_ID, FIRESTORE_DATABASE, or FIRESTORE_EVAL_COLLECTION) is empty or unset. load_issues() calls get_env_var for all three to connect to the Firestore golden-issue dataset. It is a fail-fast guard so the eval suite does not silently connect to a wrong/default database.","triggerScenarios":"load_issues() is called (from runner.run_suite or cloud_runner.main) and any of PROJECT_ID, FIRESTORE_DATABASE, or FIRESTORE_EVAL_COLLECTION is missing from the environment and the .env file. The .env file is absent, not on the Python path, or load_dotenv() was not called before load_issues().","commonSituations":"Running the eval suite locally without copying .env.example to .env. Deploying to Cloud Run where the env vars were set in a different service or region. Renaming the Firestore collection without updating FIRESTORE_EVAL_COLLECTION. The .env file exists but has Windows line endings or BOM that breaks dotenv parsing.","solutions":["Create or update .env in the caretaker-agent root with PROJECT_ID, FIRESTORE_DATABASE, and FIRESTORE_EVAL_COLLECTION set to the correct GCP values.","Run python -c \"from dotenv import load_dotenv; load_dotenv(); import os; print(os.environ.get('PROJECT_ID'))\" to confirm dotenv loads the value.","If running in Cloud Run, add all three variables in the service/job configuration or via gcloud run jobs update --set-env-vars.","Verify the .env file encoding is UTF-8 without BOM and uses Unix line endings."],"exampleFix":"# .env before (missing entries)\nGEMINI_API_KEY=...\n# after\nGEMINI_API_KEY=...\nPROJECT_ID=my-gcp-project\nFIRESTORE_DATABASE=(default)\nFIRESTORE_EVAL_COLLECTION=triage_eval_issues","handlingStrategy":"validation","validationCode":"import os\n\nREQUIRED_ENV = ['PROJECT_ID', 'FIRESTORE_DATABASE', 'FIRESTORE_EVAL_COLLECTION']\n\ndef check_required_env() -> list:\n    missing = [v for v in REQUIRED_ENV if not os.environ.get(v)]\n    return missing\n\n# Call before load_issues():\n# missing = check_required_env()\n# assert not missing, f'Missing env vars: {missing}'","typeGuard":null,"tryCatchPattern":"try:\n    issues = load_issues(filter_issues=filter_issues)\nexcept RuntimeError as e:\n    if 'environment variable' in str(e):\n        print(f'[ENV] {e} — check .env and Cloud Run config.')\n        return\n    raise","preventionTips":["Maintain a .env.example listing all three variables and document required values.","Run load_dotenv() explicitly at the top of any entry script that calls load_issues.","In Cloud Run, set env vars via the console/gcloud and verify with gcloud run jobs describe.","Add a pre-flight check that asserts all required env vars before the eval loop starts."],"tags":["configuration","env-var","firestore","gcp","evals","python"],"backgroundTag":null,"analyzedSha":"5024443c7217464a66e98f80d73172a26440bd8f","analyzedAt":"2026-08-12T06:01:53.711Z","schemaVersion":2},"datasetVersion":"2026-08-12T13:17:24.610Z"}