BerriAI/litellm · error · ValueError

S3 bucket_name is required. Set 's3_bucket_name' in litellm_

Error message

S3 bucket_name is required. Set 's3_bucket_name' in litellm_params or AWS_S3_BUCKET_NAME env var

What it means

get_complete_url() (the S3 upload target builder for Bedrock files) resolves the bucket from litellm_params['s3_bucket_name'] or the AWS_S3_BUCKET_NAME env var; with neither present it cannot form the PUT URL and raises. Note this path, unlike 1275, does accept the per-request litellm_params value.

Source

Thrown at litellm/llms/bedrock/files/transformation.py:334

            fallback_filename="file",
        )

    def get_complete_file_url(
        self,
        api_base: str | None,
        api_key: str | None,
        model: str,
        optional_params: dict,
        litellm_params: dict,
        data: CreateFileRequest,
    ) -> str:
        """
        Get the complete S3 URL for the file upload request
        """
        request_params: Final = merge_bedrock_aws_request_params(litellm_params, optional_params)
        bucket_name = litellm_params.get("s3_bucket_name") or os.getenv("AWS_S3_BUCKET_NAME")
        if not bucket_name:
            raise ValueError(
                "S3 bucket_name is required. Set 's3_bucket_name' in litellm_params or AWS_S3_BUCKET_NAME env var"
            )
        bucket_name, object_prefix = split_configured_cloud_bucket_name(bucket_name)

        s3_region_name: Final = litellm_params.get("s3_region_name") or optional_params.get("s3_region_name")
        aws_region_name: Final = s3_region_name or self._get_aws_region_name(request_params, model)

        file_data: Final = data.get("file")
        purpose: Final = data.get("purpose")
        if file_data is None:
            raise ValueError("file is required")
        if purpose is None:
            raise ValueError("purpose is required")
        extracted_file_data: Final = extract_file_data(file_data)
        object_name = self.get_object_name(extracted_file_data, purpose)
        if object_prefix:
            object_name = f"{object_prefix}/{object_name}"
        encoded_object_name: Final = encode_s3_object_key_for_url(object_name)

View on GitHub (pinned to 6c2dcb801b)

Solutions

Set AWS_S3_BUCKET_NAME=<bucket> in the process environment.
Or pass config={"s3_bucket_name": "<bucket>"} in extra litellm_params / proxy model settings.
Optionally set s3_region_name when the bucket's region differs from the Bedrock region.

Example fix

# before
litellm.create_file(file=open("batch.jsonl","rb"), purpose="batch")

# after
import os; os.environ["AWS_S3_BUCKET_NAME"] = "my-bucket"
litellm.create_file(file=open("batch.jsonl","rb"), purpose="batch")

Defensive patterns

Strategy: validation

Validate before calling

import os
bucket = os.getenv("AWS_S3_BUCKET_NAME") or litellm_params.get("s3_bucket_name")
assert bucket, "S3 bucket required for Bedrock file upload"

Try / catch

try:
    resp = litellm.create_file(file=f, purpose="batch")
except ValueError as e:
    if "s3_bucket_name" in str(e):
        raise ConfigError("set AWS_S3_BUCKET_NAME") from e
    raise

Prevention

Bake AWS_S3_BUCKET_NAME into every environment that uploads files.
Include a file-upload smoke test in deployment checks.

When it happens

Trigger: POST /v1/files (Bedrock-backed) when neither s3_bucket_name is present in the request's litellm_params (e.g. set as a model extra param / proxy config) nor AWS_S3_BUCKET_NAME is in the environment.

Common situations: First-time setup of Bedrock file uploads; env var present locally but missing in the container; forgetting to attach s3_bucket_name as extra param when calling the SDK programmatically.

Related errors

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