{"record":{"id":"75dd3aa7b6f3109e","repo":"google-gemini/gemini-cli","slug":"firestore-document-specification-must-be-a-json-ob","errorCode":null,"errorMessage":"Firestore document specification must be a JSON object.","messagePattern":"Firestore document specification must be a JSON object\\.","errorType":"validation","errorClass":"ConfigurationError","httpStatus":null,"severity":"critical","filePath":"tools/caretaker-agent/cloudrun/pr-generator/workflow/config.py","lineNumber":76,"sourceCode":"        os.environ[\"GEMINI_CLI_WORKSPACE_TRUSTED\"] = \"true\"\n\n    def load_and_validate_firestore_doc(self) -> dict[str, Any]:\n        \"\"\"Parses and validates the Firestore JSON input specification.\n\n        Returns:\n            The decoded dictionary of the Firestore document.\n\n        Raises:\n            ConfigurationError: If the document is missing or not valid JSON.\n        \"\"\"\n        if not self.firestore_doc_raw:\n            raise ConfigurationError(\n                \"Environment variable 'FIRESTORE_DOC' is required but was not set.\"\n            )\n        try:\n            doc_data = json.loads(self.firestore_doc_raw)\n            if not isinstance(doc_data, dict):\n                raise ConfigurationError(\n                    \"Firestore document specification must be a JSON object.\"\n                )\n            return doc_data\n        except json.JSONDecodeError as e:\n            raise ConfigurationError(\n                f\"Failed to parse 'FIRESTORE_DOC' as JSON: {e}\"\n            ) from e\n","sourceCodeStart":58,"sourceCodeEnd":84,"githubUrl":"https://github.com/google-gemini/gemini-cli/blob/5024443c7217464a66e98f80d73172a26440bd8f/tools/caretaker-agent/cloudrun/pr-generator/workflow/config.py#L58-L84","documentation":"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.","triggerScenarios":"json.loads(self.firestore_doc_raw) succeeds -> `if not isinstance(doc_data, dict): raise ConfigurationError(...)` at line 75-78.","commonSituations":"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.","solutions":["Set FIRESTORE_DOC to a single JSON object (curly braces), not an array.","If the upstream payload is legitimately a list, unwrap/iterate before assigning to FIRESTORE_DOC.","Validate the env var with `python -c 'import json,os; print(type(json.loads(os.environ[\"FIRESTORE_DOC\"])))'` — it must print <class 'dict'>."],"exampleFix":"# before\nexport FIRESTORE_DOC='[{\"issue_number\": 42}]'\n# after\nexport FIRESTORE_DOC='{\"issue_number\": 42}'","handlingStrategy":"validation","validationCode":"import json\ndata = json.loads(os.environ['FIRESTORE_DOC'])\nassert isinstance(data, dict), 'FIRESTORE_DOC must decode to a JSON object'","typeGuard":"def is_non_object_firestore_doc(e: Exception) -> bool:\n    return isinstance(e, ConfigurationError) and 'must be a JSON object' in str(e)","tryCatchPattern":"try:\n    doc = cfg.load_and_validate_firestore_doc()\nexcept ConfigurationError as e:\n    if 'must be a JSON object' in str(e): raise SystemExit('FIRESTORE_DOC must be a JSON object')\n    raise","preventionTips":["Publish FIRESTORE_DOC as a single object, not an array.","Validate with a JSON schema in CI for the upstream publisher."],"tags":["configuration","firestore","json-schema","python"],"backgroundTag":null,"analyzedSha":"5024443c7217464a66e98f80d73172a26440bd8f","analyzedAt":"2026-08-12T06:01:53.711Z","schemaVersion":2},"datasetVersion":"2026-08-12T13:17:24.610Z"}