google-gemini/gemini-cli · error · ValueError

Firestore document ID could not be resolved. Please set the

Error message

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.

What it means

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.

Source

Thrown at tools/caretaker-agent/cloudrun/pr-generator/workflow/db/db_interface.py:94

    issue_number: int | str | None = None,
) -> str:
    """Resolves the Firestore document ID.

    Prioritizes the FIRESTORE_ID / firestore_id environment variable or explicit doc_id
    over reconstructing the document ID from owner/repo/issue_number.
    """
    resolved_id = (
        doc_id
        or os.environ.get("FIRESTORE_ID")
        or os.environ.get("firestore_id")
    )
    if resolved_id:
        return resolved_id

    if owner and repo and issue_number is not None:
        return f"github_{owner}_{repo}_{issue_number}"

    raise ValueError(
        "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."
    )


def get_issue_ref(
    owner: str | None = None,
    repo: str | None = None,
    issue_number: int | str | None = None,
    doc_id: str | None = None,
):
    """Generates the Firestore DocumentReference for an issue using the resolved document ID."""
    resolved_id = get_firestore_id(doc_id=doc_id, owner=owner, repo=repo, issue_number=issue_number)
    return get_firestore_client().collection(COLLECTION_NAME).document(resolved_id)


@firestore.transactional
def _create_issue_tx(

View on GitHub (pinned to 5024443c72)

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.

Example fix

# before
ref = get_issue_ref(owner='org')  # missing repo, issue_number
# after
ref = get_issue_ref(owner='org', repo='name', issue_number=42)

Defensive patterns

Strategy: validation

Validate before calling

doc_id = doc_id or os.environ.get('FIRESTORE_ID')
if not doc_id and not (owner and repo and issue_number is not None):
    raise ValueError('provide doc_id or FIRESTORE_ID, or all of owner/repo/issue_number')

Type guard

def is_firestore_id_resolution_error(e: Exception) -> bool:
    return isinstance(e, ValueError) and 'document ID could not be resolved' in str(e)

Try / catch

try:
    ref = get_issue_ref(owner=owner, repo=repo, issue_number=issue_number, doc_id=doc_id)
except ValueError as e:
    if 'document ID could not be resolved' in str(e): raise SystemExit('set FIRESTORE_ID or pass owner+repo+issue_number')
    raise

Prevention

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.

When it happens

Trigger: 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.

Common situations: 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.

Related errors

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