BerriAI/litellm · error · ValueError

S3 bucket name is required. Set 's3_bucket_name' parameter o

Error message

S3 bucket name is required. Set 's3_bucket_name' parameter or {bucket_env_var} env var

What it means

Raised when LiteLLM needs to stage data to S3 (e.g. Bedrock batch/file transformation) but no bucket is configured. The bucket is resolved from litellm_params['s3_bucket_name'], then optional_params['s3_bucket_name'], then the AWS_S3_BUCKET_NAME environment variable (name configurable); if all are empty it fails.

Source

Thrown at litellm/llms/bedrock/common_utils.py:1567

        Args:
            litellm_params: LiteLLM parameters
            optional_params: Optional parameters
            bucket_env_var: Environment variable name for bucket
            key_prefix: Prefix for the S3 key

        Returns:
            Tuple of (bucket_name, object_key)
        """
        import time

        from litellm._uuid import uuid

        # Get bucket name
        bucket_name: Final = (
            litellm_params.get("s3_bucket_name") or optional_params.get("s3_bucket_name") or os.getenv(bucket_env_var)
        )
        if not bucket_name:
            raise ValueError(f"S3 bucket name is required. Set 's3_bucket_name' parameter or {bucket_env_var} env var")

        # Generate unique object key
        timestamp: Final = int(time.time())
        unique_id: Final = str(uuid.uuid4())[:8]
        object_key: Final = f"{key_prefix}-{timestamp}-{unique_id}"

        return bucket_name, object_key

    def get_error_class(self, error_message: str, status_code: int, headers: dict | httpx.Headers) -> BaseLLMException:
        """
        Get Bedrock-specific error class.
        """
        return BedrockError(status_code=status_code, message=error_message, headers=headers)

View on GitHub (pinned to 6c2dcb801b)

Solutions

Set s3_bucket_name in the request's litellm params or the model's config
Or export AWS_S3_BUCKET_NAME=<bucket> in the environment running LiteLLM and restart it
Verify the value reaches the process: print(os.getenv('AWS_S3_BUCKET_NAME')) inside the same runtime

Example fix

# before
litellm.completion(model='bedrock/...', ...)  # file transformation needs S3

# after
export AWS_S3_BUCKET_NAME=my-bucket
# or per-call:
litellm.completion(model='bedrock/...', extra_body={'s3_bucket_name': 'my-bucket'}, ...)

Defensive patterns

Strategy: validation

Validate before calling

import os

def resolve_s3_bucket(litellm_params: dict | None = None) -> str:
    bucket = (litellm_params or {}).get("s3_bucket_name") or os.getenv("AWS_S3_BUCKET_NAME")
    if not bucket:
        raise ValueError("S3 bucket name is required. Set 's3_bucket_name' parameter or AWS_S3_BUCKET_NAME env var")
    return bucket

Prevention

Set AWS_S3_BUCKET_NAME in the deployment environment (secret/configmap) and restart
Include s3_bucket_name in model config so it fails fast at config load, not mid-request
Add a boot-time env lint that asserts required S3 vars for Bedrock file features

When it happens

Trigger: Invoking Bedrock features that require S3 staging (batch jobs, file transformation for converse) without s3_bucket_name anywhere; setting the env var in a shell that did not restart the proxy; typo in the parameter key.

Common situations: Deploying LiteLLM proxy in Kubernetes with a missing/misspelled env secret, using a different env var name than the default AWS_S3_BUCKET_NAME, or passing the bucket under a config key LiteLLM does not read.

Related errors

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