google-gemini/gemini-cli · critical · RuntimeError

Missing required environment variable '{name}'. Please ensur

Error message

Missing required environment variable '{name}'. Please ensure your .env file or environment is properly configured.

What it means

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.

Source

Thrown at tools/caretaker-agent/evals/triage/helpers/dataset.py:15

"""Firestore Golden Dataset Streaming"""

import os
from typing import Dict, List, Any, Optional
from dotenv import load_dotenv
from google.cloud import firestore

load_dotenv()


def get_env_var(name: str) -> str:
    """Helper that loads an environment variable and fails fast if missing."""
    val = os.environ.get(name)
    if not val:
        raise RuntimeError(
            f"Missing required environment variable '{name}'. "
            f"Please ensure your .env file or environment is properly configured."
        )
    return val


def load_issues(filter_issues: Optional[List[int]] = None) -> List[Dict[str, Any]]:
    """Loads golden issue test cases directly from Firestore into memory."""
    project_id = get_env_var("PROJECT_ID")
    db_id = get_env_var("FIRESTORE_DATABASE")
    collection_name = get_env_var("FIRESTORE_EVAL_COLLECTION")

    db = firestore.Client(project=project_id, database=db_id)
    docs = db.collection(collection_name).stream()

    issues = []
    for doc in docs:
        data = doc.to_dict()

View on GitHub (pinned to 5024443c72)

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.

Example fix

# .env before (missing entries)
GEMINI_API_KEY=...
# after
GEMINI_API_KEY=...
PROJECT_ID=my-gcp-project
FIRESTORE_DATABASE=(default)
FIRESTORE_EVAL_COLLECTION=triage_eval_issues

Defensive patterns

Strategy: validation

Validate before calling

import os

REQUIRED_ENV = ['PROJECT_ID', 'FIRESTORE_DATABASE', 'FIRESTORE_EVAL_COLLECTION']

def check_required_env() -> list:
    missing = [v for v in REQUIRED_ENV if not os.environ.get(v)]
    return missing

# Call before load_issues():
# missing = check_required_env()
# assert not missing, f'Missing env vars: {missing}'

Try / catch

try:
    issues = load_issues(filter_issues=filter_issues)
except RuntimeError as e:
    if 'environment variable' in str(e):
        print(f'[ENV] {e} — check .env and Cloud Run config.')
        return
    raise

Prevention

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.

When it happens

Trigger: 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().

Common situations: 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.

Related errors

AI-assisted analysis of google-gemini/gemini-cli@5024443c72 (2026-08-12). Data as JSON: /api/errors/c05e1be3b60a7faa. Report an issue: GitHub.