BerriAI/litellm · error · ValueError

GCS_BUCKET_NAME is not set in the environment, but GCS Bucke

Error message

GCS_BUCKET_NAME is not set in the environment, but GCS Bucket is being used as a logging callback. Please set 'GCS_BUCKET_NAME' in the environment.

What it means

Raised in the dynamic-params branch of GCS bucket logging setup: when per-request dynamic params are supplied, the bucket name is resolved as standard_callback_dynamic_params['gcs_bucket_name'] falling back to the class-level BUCKET_NAME; if both are None the logging callback cannot proceed. BUCKET_NAME itself comes from the GCS_BUCKET_NAME env var.

Source

Thrown at litellm/integrations/gcs_bucket/gcs_bucket_base.py:163

            kwargs = {}

        standard_callback_dynamic_params: Final[StandardCallbackDynamicParams | None] = kwargs.get(
            "standard_callback_dynamic_params", None
        )

        bucket_name: str
        path_service_account: str | None
        if standard_callback_dynamic_params is not None:
            verbose_logger.debug("Using dynamic GCS logging")
            verbose_logger.debug("standard_callback_dynamic_params: %s", standard_callback_dynamic_params)

            _bucket_name: str | None = standard_callback_dynamic_params.get("gcs_bucket_name", None) or self.BUCKET_NAME
            _path_service_account: Final[str | None] = (
                standard_callback_dynamic_params.get("gcs_path_service_account", None) or self.path_service_account_json
            )

            if _bucket_name is None:
                raise ValueError(
                    "GCS_BUCKET_NAME is not set in the environment, but GCS Bucket is being used as a logging callback. Please set 'GCS_BUCKET_NAME' in the environment."
                )
            bucket_name = _bucket_name
            path_service_account = _path_service_account
            vertex_instance = await self.get_or_create_vertex_instance(credentials=path_service_account)
        else:
            # If no dynamic parameters, use the default instance
            if self.BUCKET_NAME is None:
                raise ValueError(
                    "GCS_BUCKET_NAME is not set in the environment, but GCS Bucket is being used as a logging callback. Please set 'GCS_BUCKET_NAME' in the environment."
                )
            bucket_name = self.BUCKET_NAME
            path_service_account = self.path_service_account_json
            vertex_instance = await self.get_or_create_vertex_instance(credentials=path_service_account)

        return GCSLoggingConfig(
            bucket_name=bucket_name,
            vertex_instance=vertex_instance,

View on GitHub (pinned to 6c2dcb801b)

Solutions

Set GCS_BUCKET_NAME in the proxy environment as the safe fallback.
Or populate gcs_bucket_name in the dynamic callback params for the affected request/team.
Audit dynamic logging config rows for empty gcs_bucket_name values.

Example fix

# before: dynamic params without bucket, GCS_BUCKET_NAME unset

# after
export GCS_BUCKET_NAME=my-default-logs-bucket

Defensive patterns

Strategy: validation

Validate before calling

import os

bucket = dynamic_params.get("gcs_bucket_name") or os.getenv("GCS_BUCKET_NAME")
if not bucket:
    raise ValueError("Set gcs_bucket_name in dynamic logging params or GCS_BUCKET_NAME in the env")

Type guard

def gcs_dynamic_params_valid(p: dict | None) -> bool:
    import os
    if p is None:
        return True
    return bool(p.get("gcs_bucket_name") or os.getenv("GCS_BUCKET_NAME"))

Prevention

Always set GCS_BUCKET_NAME as the default even when using per-request buckets.
Add a NOT NULL / non-empty constraint on gcs_bucket_name in dynamic logging config tables.
Test dynamic-params rows in staging with the env var deliberately unset.

When it happens

Trigger: A request carries dynamic GCS logging params (gcs_path_service_account or similar) but neither gcs_bucket_name in the dynamic params nor GCS_BUCKET_NAME in the proxy environment is set.

Common situations: Per-team/per-request bucket routing configured in the DB with the bucket field left blank on some rows; env var present in one replica but missing in another.

Related errors

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