BerriAI/litellm · error · ValueError

FOCUS_S3_BUCKET_NAME must be provided for S3 exports

Error message

FOCUS_S3_BUCKET_NAME must be provided for S3 exports

What it means

The Focus export destination factory resolves S3 settings from the destination_config overrides first, then from environment variables. When building an 's3' provider config it requires a bucket name; if neither overrides['bucket_name'] nor the FOCUS_S3_BUCKET_NAME env var is set, it raises this ValueError. All other S3 keys (region, endpoint, keys, session token) are optional and filtered out when None.

Source

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

        raise NotImplementedError(f"Provider '{provider}' not supported for Focus export")

    @staticmethod
    def _resolve_config(
        *,
        provider: str,
        overrides: dict[str, Any],
    ) -> dict[str, Any]:
        if provider == "s3":
            resolved = {
                "bucket_name": overrides.get("bucket_name") or os.getenv("FOCUS_S3_BUCKET_NAME"),
                "region_name": overrides.get("region_name") or os.getenv("FOCUS_S3_REGION_NAME"),
                "endpoint_url": overrides.get("endpoint_url") or os.getenv("FOCUS_S3_ENDPOINT_URL"),
                "aws_access_key_id": overrides.get("aws_access_key_id") or os.getenv("FOCUS_S3_ACCESS_KEY"),
                "aws_secret_access_key": overrides.get("aws_secret_access_key") or os.getenv("FOCUS_S3_SECRET_KEY"),
                "aws_session_token": overrides.get("aws_session_token") or os.getenv("FOCUS_S3_SESSION_TOKEN"),
            }
            if not resolved.get("bucket_name"):
                raise ValueError("FOCUS_S3_BUCKET_NAME must be provided for S3 exports")
            return {k: v for k, v in resolved.items() if v is not None}
        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"),
            }

View on GitHub (pinned to 6c2dcb801b)

Solutions

  1. Set the env var: export FOCUS_S3_BUCKET_NAME=my-focus-bucket (or add it to the proxy's environment/.env).
  2. Or pass bucket_name explicitly in the destination config: {"provider": "s3", "bucket_name": "my-focus-bucket"}.
  3. Verify with a pre-flight check that os.getenv('FOCUS_S3_BUCKET_NAME') is non-empty before creating the export.
  4. If using a different object-store provider name (e.g. custom endpoint), confirm 's3' is still the right provider string and the bucket env var matches the deployment environment.

Example fix

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

# after
export FOCUS_S3_BUCKET_NAME=focus-exports  # shell
# or
config = focus_destination_config(provider="s3", overrides={"bucket_name": "focus-exports"})
Defensive patterns

Strategy: validation

Validate before calling

import os

bucket = overrides.get("bucket_name") or os.getenv("FOCUS_S3_BUCKET_NAME")
if not bucket:
    raise SystemExit("Set FOCUS_S3_BUCKET_NAME or pass bucket_name before creating the S3 Focus export")

Try / catch

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

Prevention

When it happens

Trigger: Creating a Focus export with provider="s3" while passing no bucket_name in the destination config dict and having no FOCUS_S3_BUCKET_NAME exported in the process environment (or an empty-string value, since the check is falsy-based).

Common situations: Running the LiteLLM proxy in a container/k8s where the FOCUS_S3_BUCKET_NAME secret was not mounted; typos in the env var name; relying on AWS_PROFILE/instance roles and assuming a bucket default exists (there is none); passing bucket_name under a different key such as 'bucket'.

Related errors

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