{"id":"3dfbb5c6f5ab92a2","repo":"boto/boto3","slug":"failed-to-upload-filename-to-bucket-key-e","errorCode":null,"errorMessage":"Failed to upload {filename} to {bucket}/{key}: {e}","messagePattern":"Failed to upload (.+?) to (.+?)/(.+?): (.+?)","errorType":"exception","errorClass":"S3UploadFailedError","httpStatus":null,"severity":"error","filePath":"boto3/s3/transfer.py","lineNumber":458,"sourceCode":"            :py:meth:`S3.Client.upload_fileobj`\n        \"\"\"\n        if isinstance(filename, PathLike):\n            filename = fspath(filename)\n        if not isinstance(filename, str):\n            raise ValueError('Filename must be a string or a path-like object')\n\n        subscribers = self._get_subscribers(callback)\n        future = self._manager.upload(\n            filename, bucket, key, extra_args, subscribers\n        )\n        try:\n            future.result()\n        # If a client error was raised, add the backwards compatibility layer\n        # that raises a S3UploadFailedError. These specific errors were only\n        # ever thrown for upload_parts but now can be thrown for any related\n        # client error.\n        except ClientError as e:\n            raise S3UploadFailedError(\n                f\"Failed to upload {filename} to {bucket}/{key}: {e}\"\n            )\n\n    def download_file(\n        self, bucket, key, filename, extra_args=None, callback=None\n    ):\n        \"\"\"Download an S3 object to a file.\n\n        Variants have also been injected into S3 client, Bucket and Object.\n        You don't have to use S3Transfer.download_file() directly.\n\n        .. seealso::\n            :py:meth:`S3.Client.download_file`\n            :py:meth:`S3.Client.download_fileobj`\n        \"\"\"\n        if isinstance(filename, PathLike):\n            filename = fspath(filename)\n        if not isinstance(filename, str):","sourceCodeStart":440,"sourceCodeEnd":476,"githubUrl":"https://github.com/boto/boto3/blob/c7b4afac237b976d48395d7523eaf7cec3a450b3/boto3/s3/transfer.py#L440-L476","documentation":"Raised as S3UploadFailedError when the underlying managed upload's future.result() raises a botocore ClientError. upload_file wraps any ClientError originating from PutObject/CreateMultipartUpload/UploadPart/CompleteMultipartUpload into S3UploadFailedError so callers have a single boto3 exception to catch for upload failures; the message includes the local filename, target bucket/key, and the wrapped error. The root cause is whatever the S3 service (or transport) rejected.","triggerScenarios":"Calling s3.upload_file(filename, bucket, key) (or the Bucket/Object variants) and hitting a ClientError: NoSuchBucket, AccessDenied/403, RequestTimeout, slow-down/503, invalid ExtraArgs, signature/credential failures, or a connection reset during a multipart upload.","commonSituations":"Missing IAM s3:PutObject permission; wrong bucket name or region; expired temporary credentials; uploading to a bucket with object-lock/KMS where the key policy or KMS grant denies the caller; transient throttling on a busy bucket.","solutions":["Inspect e.last_exception / the wrapped ClientError response['Error']['Code'] and response['Error']['Message'] to identify the exact S3 failure.","For AccessDenied, verify the IAM principal has s3:PutObject (and kms:GenerateDataKey if SSE-KMS) on the target bucket, and that the bucket policy does not deny it.","For NoSuchBucket, confirm the bucket name and region and that the client is in the right region.","For throttling/timeouts, increase TransferConfig max_concurrency/retry counts or add exponential backoff.","Wrap the call in try/except S3UploadFailedError and retry idempotently on transient codes."],"exampleFix":"// before\ns3.upload_file('/tmp/data.bin', 'bkt', 'key')  # surfaces as S3UploadFailedError\n\n// after\nfrom boto3.exceptions import S3UploadFailedError\ntry:\n    s3.upload_file('/tmp/data.bin', 'bkt', 'key')\nexcept S3UploadFailedError as e:\n    code = e.args[0].split(':')[-1]  # or parse the wrapped ClientError\n    log.error('upload failed: %s', e)\n    raise","handlingStrategy":"try-catch","validationCode":"# Pre-flight: confirm bucket/region and credentials resolve before upload\nsts = boto3.client('sts')\nsts.get_caller_identity()  # raises if credentials are missing\nclient = boto3.client('s3', region_name=region)\nclient.head_bucket(Bucket=bucket)  # raises if bucket/permission wrong","typeGuard":"def can_put_object(client, bucket, key) -> bool:\n    try:\n        client.head_bucket(Bucket=bucket)\n        return True\n    except Exception:\n        return False","tryCatchPattern":"from boto3.exceptions import S3UploadFailedError\ntry:\n    s3.upload_file(filename, bucket, key)\nexcept S3UploadFailedError as e:\n    cause = e.args[0]\n    # parse the wrapped ClientError code from cause and branch on it\n    raise","preventionTips":["Verify IAM s3:PutObject (and kms:GenerateDataKey for SSE-KMS) on the caller before deploying.","Confirm bucket name and region match the client configuration.","Wrap uploads in try/except S3UploadFailedError and retry transient codes (5xx, timeouts) with backoff.","Validate ExtraArgs keys against S3Transfer.ALLOWED_UPLOAD_ARGS before calling."],"tags":["boto3","s3","upload","client-error","iam","network"],"analyzedSha":"c7b4afac237b976d48395d7523eaf7cec3a450b3","analyzedAt":"2026-08-04T20:35:51.598Z","schemaVersion":2}