google-gemini/gemini-cli · critical · ConfigurationError

Environment variable 'FIRESTORE_DOC' is required but was not

Error message

Environment variable 'FIRESTORE_DOC' is required but was not set.

What it means

ConfigurationError 'Environment variable FIRESTORE_DOC is required but was not set.' is raised by load_and_validate_firestore_doc when self.firestore_doc_raw is falsy. The PR-generator CloudRun service expects every invocation to carry a FIRESTORE_DOC env var describing the job; without it the service cannot proceed.

Source

Thrown at tools/caretaker-agent/cloudrun/pr-generator/workflow/config.py:70

            self.repo_url.rstrip("/").split("/")[-1].replace(".git", "")
        )
        self.pr_repo_path: str = os.path.join(self.pr_dir, self.repo_name)
        self.eval_repo_path: str = os.path.join(self.eval_dir, self.repo_name)

        # Global environment variables to trust the CLI
        os.environ["GEMINI_CLI_WORKSPACE_TRUSTED"] = "true"

    def load_and_validate_firestore_doc(self) -> dict[str, Any]:
        """Parses and validates the Firestore JSON input specification.

        Returns:
            The decoded dictionary of the Firestore document.

        Raises:
            ConfigurationError: If the document is missing or not valid JSON.
        """
        if not self.firestore_doc_raw:
            raise ConfigurationError(
                "Environment variable 'FIRESTORE_DOC' is required but was not set."
            )
        try:
            doc_data = json.loads(self.firestore_doc_raw)
            if not isinstance(doc_data, dict):
                raise ConfigurationError(
                    "Firestore document specification must be a JSON object."
                )
            return doc_data
        except json.JSONDecodeError as e:
            raise ConfigurationError(
                f"Failed to parse 'FIRESTORE_DOC' as JSON: {e}"
            ) from e

View on GitHub (pinned to 5024443c72)

Solutions

Set FIRESTORE_DOC to a valid JSON document string in the CloudRun service env.
If testing locally, export FIRESTORE_DOC='{}' (then satisfy [256] by filling it).
Verify the upstream Firestore trigger / scheduler still writes the env var on each invocation.

Example fix

# before
# env: (FIRESTORE_DOC unset)
# after
export FIRESTORE_DOC='{"issue_number": 42, "owner": "org", "repo": "name"}'

Defensive patterns

Strategy: validation

Validate before calling

raw = os.environ.get('FIRESTORE_DOC')
if not raw:
    raise SystemExit('FIRESTORE_DOC env var required')

Type guard

def is_missing_firestore_doc(e: Exception) -> bool:
    return isinstance(e, ConfigurationError) and 'FIRESTORE_DOC' in str(e) and 'not set' in str(e)

Try / catch

try:
    doc = cfg.load_and_validate_firestore_doc()
except ConfigurationError as e:
    if 'not set' in str(e): raise SystemExit('configure FIRESTORE_DOC env var')
    raise

Prevention

Add a startup assertion for FIRESTORE_DOC so missing-env fails the deploy loudly.
Keep the env var name in the service's documented required-env list.

When it happens

Trigger: Configuration().firestore_doc_raw (read from FIRESTORE_DOC env at construction) is empty/None -> load_and_validate_firestore_doc() -> `if not self.firestore_doc_raw: raise ConfigurationError(...)`.

Common situations: Cloud Function/Run deploy missing the FIRESTORE_DOC env var; test harness invoking the service locally without setting it; Firestore trigger wiring changed and no longer passes the doc JSON.

Related errors

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