google-gemini/gemini-cli · critical · ConfigurationError

Failed to parse 'FIRESTORE_DOC' as JSON: {e}

Error message

Failed to parse 'FIRESTORE_DOC' as JSON: {e}

What it means

ConfigurationError 'Failed to parse FIRESTORE_DOC as JSON: e' wraps a json.JSONDecodeError raised when load_and_validate_firestore_doc calls json.loads on firestore_doc_raw. The original decode error (position, message) is preserved via `from e`.

Source

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

        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. Run the value through a JSON validator / `python -m json.tool` and fix the syntax error at the reported position.
2. Re-deploy the CloudRun service with the corrected FIRESTORE_DOC value.
3. If the doc is generated upstream, fix the publisher to emit strict JSON.

Example fix

# before
export FIRESTORE_DOC="{'issue_number': 42,}"  # single quotes + trailing comma
# after
export FIRESTORE_DOC='{"issue_number": 42}'

import json
try:
    json.loads(os.environ['FIRESTORE_DOC'])
except json.JSONDecodeError as e:
    raise SystemExit(f'FIRESTORE_DOC is not valid JSON: {e}')

def is_firestore_json_parse_error(e: Exception) -> bool:
    return isinstance(e, ConfigurationError) and 'parse' in str(e).lower() and 'FIRESTORE_DOC' in str(e)

try:
    doc = cfg.load_and_validate_firestore_doc()
except ConfigurationError as e:
    if 'parse' in str(e).lower(): raise SystemExit('fix FIRESTORE_DOC JSON syntax')
    raise

When it happens

Trigger: self.firestore_doc_raw is truthy but not valid JSON -> json.loads raises JSONDecodeError -> except json.JSONDecodeError as e: raise ConfigurationError(f"Failed to parse 'FIRESTORE_DOC' as JSON: {e}") from e.

Common situations: Trailing comma in the env JSON; single quotes instead of double quotes; unescaped newlines inside strings; copy-paste introduced smart quotes; the env var was double-quoted at deploy time and now contains a leading/trailing quote char.

Understand the failure class

• Parsing and encoding errors: unexpected token, malformed input — why parsers reject input and how to find the real culprit.

Related errors

• Environment variable 'FIRESTORE_DOC' is required but was not
• Firestore document specification must be a JSON object.
• 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/a72daaa25be27d86. Report an issue: GitHub.