google-gemini/gemini-cli · critical · ConfigurationError

Firestore document specification must be a JSON object.

Error message

Firestore document specification must be a JSON object.

What it means

ConfigurationError 'Firestore document specification must be a JSON object.' is raised when FIRESTORE_DOC parses as valid JSON but the top-level value is not a dict (e.g. a JSON array, string, number). The downstream code keys into the dict, so a non-object is unrecoverable.

Source

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

        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

1. Set FIRESTORE_DOC to a single JSON object (curly braces), not an array.
2. If the upstream payload is legitimately a list, unwrap/iterate before assigning to FIRESTORE_DOC.
3. Validate the env var with `python -c 'import json,os; print(type(json.loads(os.environ["FIRESTORE_DOC"])))'` — it must print <class 'dict'>.

Example fix

# before
export FIRESTORE_DOC='[{"issue_number": 42}]'
# after
export FIRESTORE_DOC='{"issue_number": 42}'

import json
data = json.loads(os.environ['FIRESTORE_DOC'])
assert isinstance(data, dict), 'FIRESTORE_DOC must decode to a JSON object'

def is_non_object_firestore_doc(e: Exception) -> bool:
    return isinstance(e, ConfigurationError) and 'must be a JSON object' in str(e)

try:
    doc = cfg.load_and_validate_firestore_doc()
except ConfigurationError as e:
    if 'must be a JSON object' in str(e): raise SystemExit('FIRESTORE_DOC must be a JSON object')
    raise

When it happens

Trigger: json.loads(self.firestore_doc_raw) succeeds -> `if not isinstance(doc_data, dict): raise ConfigurationError(...)` at line 75-78.

Common situations: FIRESTORE_DOC set to a JSON array of issues instead of a single object; raw value quoted twice so it parses to a string; upstream publisher emits a list wrapper.

Related errors

• Environment variable 'FIRESTORE_DOC' is required but was not
• Failed to parse 'FIRESTORE_DOC' as JSON: {e}
• Missing required environment variable '{name}'. Please ensur
• Firestore document ID could not be resolved. Please set the
• EVAL_CONFIG must be a JSON object, got {type(cfg).__name__}

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