BerriAI/litellm · error · ValueError

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

Error message

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

What it means

Raised by BedrockFileTransformation.get_s3_bucket_and_key_from_config when no S3 bucket can be resolved for uploads. The bucket is looked up in three places, in order: litellm_params['s3_bucket_name'], optional_params['s3_bucket_name'], then the environment variable named by bucket_env_var (default AWS_S3_BUCKET_NAME). If all three are empty the call is rejected before any upload is attempted.

Solutions

Pass s3_bucket_name explicitly: litellm.completion(..., extra_body={'s3_bucket_name': 'my-bucket'}) or set it as a litellm_param in config.yaml
Or export the env var: export AWS_S3_BUCKET_NAME=my-bucket, then restart the proxy/app so it is re-read
Check the value is non-empty and has no quotes/whitespace: print(repr(os.getenv('AWS_S3_BUCKET_NAME')))
If using the proxy, add it to the environment block of your deployment (docker-compose/systemd/k8s env), not just your local shell

Example fix

# before
response = litellm.completion(model='bedrock/...', messages=..., file_id='...')  # no bucket configured

# after
response = litellm.completion(
    model='bedrock/...',
    messages=...,
    file_id='...',
    extra_body={'s3_bucket_name': 'my-bucket'},
)

Defensive patterns

Strategy: validation

Validate before calling

import os

def resolve_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 RuntimeError(
            'Set s3_bucket_name param or AWS_S3_BUCKET_NAME env var before bedrock file calls'
        )
    return bucket

resolve_bucket()  # fail fast at startup/config-load

Try / catch

try:
    bucket, key = transformer.get_s3_bucket_and_key_from_config(litellm_params, optional_params)
except ValueError as e:
    if 's3_bucket_name' in str(e):
        os.environ.setdefault('AWS_S3_BUCKET_NAME', FALLBACK_BUCKET)
        bucket, key = transformer.get_s3_bucket_and_key_from_config(litellm_params, optional_params)
    else:
        raise

Prevention

Configure s3_bucket_name once in config.yaml rather than per request
Add AWS_S3_BUCKET_NAME to your deployment env spec (compose/k8s manifest)
Add a config-validation step that fails startup when the bucket is unresolved

When it happens

Trigger: Using Bedrock file-based transformations (e.g. large document/file inputs that must be staged in S3) without setting s3_bucket_name in the request/config and without AWS_S3_BUCKET_NAME in the environment; setting the env var in a different shell or process than the one running litellm; passing an empty string instead of omitting the key.

Common situations: Proxy configs (config.yaml) missing the s3_bucket_name litellm_param; CI/containers where AWS_S3_BUCKET_NAME was never exported; typos in the env var name; assuming the bucket is derived from AWS credentials (it is not — it must be configured explicitly).

Understand the failure class

Background: "environment variable is not set" and "Missing keys in environment" errors: what missing required env var messages mean and how to fix them — this error's family across 28 libraries.

Related errors

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

Appendix: 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 77b7c6c40c)