BerriAI/litellm · error · ValueError

FOCUS_GCS_BUCKET_NAME must be provided for GCS exports

Error message

FOCUS_GCS_BUCKET_NAME must be provided for GCS exports

What it means

For provider="gcs", the factory resolves bucket_name from overrides or FOCUS_GCS_BUCKET_NAME and requires it. service_account_json (or FOCUS_GCS_PATH_SERVICE_ACCOUNT) is optional — the GCS destination falls back to default application credentials — but the bucket name is mandatory.

Source

Thrown at litellm/integrations/focus/destinations/factory.py:74

        if provider == "vantage":
            resolved = {
                "api_key": overrides.get("api_key") or os.getenv("VANTAGE_API_KEY"),
                "integration_token": overrides.get("integration_token") or os.getenv("VANTAGE_INTEGRATION_TOKEN"),
                "base_url": overrides.get("base_url") or os.getenv("VANTAGE_BASE_URL", "https://api.vantage.sh"),
            }
            if not resolved.get("api_key"):
                raise ValueError("VANTAGE_API_KEY must be provided for Vantage exports")
            if not resolved.get("integration_token"):
                raise ValueError("VANTAGE_INTEGRATION_TOKEN must be provided for Vantage exports")
            return {k: v for k, v in resolved.items() if v is not None}
        if provider == "gcs":
            resolved = {
                "bucket_name": overrides.get("bucket_name") or os.getenv("FOCUS_GCS_BUCKET_NAME"),
                "service_account_json": overrides.get("service_account_json")
                or os.getenv("FOCUS_GCS_PATH_SERVICE_ACCOUNT"),
            }
            if not resolved.get("bucket_name"):
                raise ValueError("FOCUS_GCS_BUCKET_NAME must be provided for GCS exports")
            return {k: v for k, v in resolved.items() if v is not None}
        if provider == "mavvrik":
            resolved = {
                "api_key": overrides.get("api_key") or os.getenv("MAVVRIK_API_KEY"),
                "api_endpoint": overrides.get("api_endpoint") or os.getenv("MAVVRIK_API_ENDPOINT"),
                "connection_id": overrides.get("connection_id") or os.getenv("MAVVRIK_CONNECTION_ID"),
            }
            return {k: v for k, v in resolved.items() if v is not None}
        raise NotImplementedError(f"Provider '{provider}' not supported for Focus export configuration")

View on GitHub (pinned to 6c2dcb801b)

Solutions

Set FOCUS_GCS_BUCKET_NAME=my-gcs-bucket in the environment.
Or pass bucket_name in the destination config overrides for provider 'gcs'.
Double-check you set the GCS variable, not FOCUS_S3_BUCKET_NAME, when exporting to Google Cloud Storage.
Optionally also set FOCUS_GCS_PATH_SERVICE_ACCOUNT if the workload has no default credentials.

Example fix

# before
config = focus_destination_config(provider="gcs", overrides={})

# after
config = focus_destination_config(provider="gcs", overrides={"bucket_name": "my-focus-export-bucket"})

Defensive patterns

Strategy: validation

Validate before calling

import os

if not (overrides.get("bucket_name") or os.getenv("FOCUS_GCS_BUCKET_NAME")):
    raise SystemExit("FOCUS_GCS_BUCKET_NAME missing: set it before enabling the GCS Focus export")

Try / catch

try:
    cfg = focus_destination_config(provider="gcs", overrides=overrides)
except ValueError as e:
    if "FOCUS_GCS_BUCKET_NAME" in str(e):
        log_config_error("gcs", missing=["bucket_name"])
    raise

Prevention

Namespace env vars clearly per provider (FOCUS_S3_* vs FOCUS_GCS_*) in your deployment manifest comments.
Assert non-empty (not merely present) values — the factory rejects empty strings.

When it happens

Trigger: Building a Focus export with provider="gcs" with no bucket_name in the config dict and no FOCUS_GCS_BUCKET_NAME env var.

Common situations: Confusing this with the S3 bucket var (FOCUS_S3_BUCKET_NAME) and setting the wrong one; Workload Identity setups where devs assume the bucket is inferred from the SA bindings; missing env in Helm values; bucket name present but as None due to optional config templating.

Related errors

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