{"record":{"id":"393857dbb6ffac3c","repo":"google-gemini/gemini-cli","slug":"firestore-document-id-could-not-be-resolved-pleas","errorCode":null,"errorMessage":"Firestore document ID could not be resolved. Please set the 'FIRESTORE_ID' environment variable or provide explicit doc_id or owner, repo, and issue_number.","messagePattern":"Firestore document ID could not be resolved\\. Please set the 'FIRESTORE_ID' environment variable or provide explicit doc_id or owner, repo, and issue_number\\.","errorType":"validation","errorClass":"ValueError","httpStatus":null,"severity":"error","filePath":"tools/caretaker-agent/cloudrun/pr-generator/workflow/db/db_interface.py","lineNumber":94,"sourceCode":"    issue_number: int | str | None = None,\n) -> str:\n    \"\"\"Resolves the Firestore document ID.\n\n    Prioritizes the FIRESTORE_ID / firestore_id environment variable or explicit doc_id\n    over reconstructing the document ID from owner/repo/issue_number.\n    \"\"\"\n    resolved_id = (\n        doc_id\n        or os.environ.get(\"FIRESTORE_ID\")\n        or os.environ.get(\"firestore_id\")\n    )\n    if resolved_id:\n        return resolved_id\n\n    if owner and repo and issue_number is not None:\n        return f\"github_{owner}_{repo}_{issue_number}\"\n\n    raise ValueError(\n        \"Firestore document ID could not be resolved. Please set the 'FIRESTORE_ID' \"\n        \"environment variable or provide explicit doc_id or owner, repo, and issue_number.\"\n    )\n\n\ndef get_issue_ref(\n    owner: str | None = None,\n    repo: str | None = None,\n    issue_number: int | str | None = None,\n    doc_id: str | None = None,\n):\n    \"\"\"Generates the Firestore DocumentReference for an issue using the resolved document ID.\"\"\"\n    resolved_id = get_firestore_id(doc_id=doc_id, owner=owner, repo=repo, issue_number=issue_number)\n    return get_firestore_client().collection(COLLECTION_NAME).document(resolved_id)\n\n\n@firestore.transactional\ndef _create_issue_tx(","sourceCodeStart":76,"sourceCodeEnd":112,"githubUrl":"https://github.com/google-gemini/gemini-cli/blob/5024443c7217464a66e98f80d73172a26440bd8f/tools/caretaker-agent/cloudrun/pr-generator/workflow/db/db_interface.py#L76-L112","documentation":"ValueError 'Firestore document ID could not be resolved...' is raised by get_firestore_id when none of its inputs can produce an id: doc_id is None, FIRESTORE_ID/firestore_id env vars are unset, AND (owner, repo, issue_number) is incomplete. The function cannot construct a DocumentReference without an id, so it aborts.","triggerScenarios":"get_firestore_id(doc_id=None, owner=None, repo='x') or any combination where doc_id is falsy, no FIRESTORE_ID env, and not all of (owner, repo, issue_number is not None) are present -> raise ValueError at line 94-97.","commonSituations":"Caller forgot to pass issue_number (None) or passed owner but not repo; the workflow ran without FIRESTORE_ID and the GitHub metadata was incomplete; partial refactor left a call site with missing kwargs.","solutions":["Pass all three: owner, repo, issue_number — or an explicit doc_id.","Set the FIRESTORE_ID env var in the deployed environment as a fallback.","Validate inputs at the call site before invoking get_firestore_id / get_issue_ref."],"exampleFix":"# before\nref = get_issue_ref(owner='org')  # missing repo, issue_number\n# after\nref = get_issue_ref(owner='org', repo='name', issue_number=42)","handlingStrategy":"validation","validationCode":"doc_id = doc_id or os.environ.get('FIRESTORE_ID')\nif not doc_id and not (owner and repo and issue_number is not None):\n    raise ValueError('provide doc_id or FIRESTORE_ID, or all of owner/repo/issue_number')","typeGuard":"def is_firestore_id_resolution_error(e: Exception) -> bool:\n    return isinstance(e, ValueError) and 'document ID could not be resolved' in str(e)","tryCatchPattern":"try:\n    ref = get_issue_ref(owner=owner, repo=repo, issue_number=issue_number, doc_id=doc_id)\nexcept ValueError as e:\n    if 'document ID could not be resolved' in str(e): raise SystemExit('set FIRESTORE_ID or pass owner+repo+issue_number')\n    raise","preventionTips":["Always pass the full (owner, repo, issue_number) triple or an explicit doc_id.","Set FIRESTORE_ID env var as a fallback in deployed environments."],"tags":["firestore","validation","missing-argument","python"],"backgroundTag":null,"analyzedSha":"5024443c7217464a66e98f80d73172a26440bd8f","analyzedAt":"2026-08-12T06:01:53.711Z","schemaVersion":2},"datasetVersion":"2026-08-12T13:17:24.610Z"}