BerriAI/litellm · error · ValueError

start_time_utc is required for getting a payload from GCS Bu

Error message

start_time_utc is required for getting a payload from GCS Bucket

What it means

GCSBucketLogger.get_request_response_payload raises ValueError when start_time_utc is None. The lookup strategy derives object names from the request date (trying same day, +1 day, -1 day), so without a start time there is no way to locate the object in the bucket.

Source

Thrown at litellm/integrations/gcs_bucket/gcs_bucket.py:316

        if "gcs_log_id" in _metadata:
            safe_log_id: Final = sanitize_cloud_object_component(_metadata.get("gcs_log_id"), fallback="")
            if safe_log_id:
                object_name = f"{current_date}/custom-{uuid.uuid4().hex}-{safe_log_id}"

        return object_name

    async def get_request_response_payload(
        self,
        request_id: str,
        start_time_utc: datetime | None,
        end_time_utc: datetime | None,
    ) -> dict | None:
        """
        Get the request and response payload for a given `request_id`
        Tries current day, next day, and previous day until it finds the payload
        """
        if start_time_utc is None:
            raise ValueError("start_time_utc is required for getting a payload from GCS Bucket")

        dates_to_try: Final = [
            start_time_utc,
            start_time_utc + timedelta(days=1),
            start_time_utc - timedelta(days=1),
        ]
        date_str = None
        for date in dates_to_try:
            try:
                date_str = self._get_object_date_from_datetime(datetime_obj=date)
                object_name = self._generate_success_object_name(
                    request_date_str=date_str,
                    response_id=request_id,
                )
                response = await self.download_gcs_object(object_name)

                if response is not None:
                    loaded_response = json.loads(response)

View on GitHub (pinned to 6c2dcb801b)

Solutions

Pass the request's start_time (UTC) — e.g. from the spend/logs DB record for that request_id.
If start_time is genuinely unavailable, fetch the log row first to recover it before calling this method.
Guard at the call site: skip/return early when start_time_utc is None.

Example fix

# before
payload = await gcs_logger.get_request_response_payload(request_id, None, None)

# after
if start_time_utc is None:
    return None
payload = await gcs_logger.get_request_response_payload(request_id, start_time_utc, None)

Defensive patterns

Strategy: validation

Validate before calling

if start_time_utc is None:
    return None  # or fetch the log row to obtain start_time first
payload = await gcs_logger.get_request_response_payload(request_id, start_time_utc, end_time_utc)

Type guard

def has_start_time(d: datetime | None) -> bool:
    return d is not None

Prevention

Always source start_time from the request's log record before asking GCS for the payload.
Make the field required in your request-fetch API rather than optional.
Return a clear 'payload unavailable' response instead of propagating the ValueError to clients.

When it happens

Trigger: Calling get_request_response_payload(request_id, None, end_time_utc) — typically a caller passing an optional start_time that was never populated, or a request record whose start_time field is missing.

Common situations: Proxy UI/API fetching a logged payload for a request whose metadata lacks a start timestamp; refactoring that made start_time optional without handling None.

Related errors

AI-assisted analysis of BerriAI/litellm@6c2dcb801b (2026-08-15). Data as JSON: /api/errors/b1044d5ab916a5c9. Report an issue: GitHub.