Announcement: S3 default integrity change

TL;DR

boto3 1.36.0 turned on default S3 integrity checksums. If PutObject now fails with XAmzContentSHA256Mismatch, pin back to boto3<1.36.0, botocore<1.36.0, s3transfer<0.11.0 as a stopgap. Longer term, upgrade and keep the checksums on; only disable the default integrity behavior per the AWS docs if you have a specific reason.

The error

XAmzContentSHA256Mismatch: The Content-SHA256 you specified did not match what we received.

Starts after upgrading to boto3 1.36.0 or newer.

Fix it

1. Confirm the boto3 version:

   pip show boto3 | grep Version

   Success check: version is 1.36.0 or newer, confirming the behavior change applies.

2. Stopgap: pin the previous minor line:

   boto3<1.36.0
   botocore<1.36.0
   s3transfer<0.11.0

   Success check: PutObject succeeds again after reinstalling.

3. Proper fix: upgrade to the latest boto3 and keep default integrity on. Success check: puts succeed with checksums enabled (they protect S3 integrity).

4. Only if you have a specific reason, disable the default integrity behavior per the AWS SDK docs on data integrity. Success check: puts succeed; document why checksums are off.

When this applies

• PutObject/upload_file fails with XAmzContentSHA256Mismatch right after a boto3 upgrade to 1.36.0+.
• Proxies or middleware that rewrite request bodies, which invalidates the checksum.

When it does not apply

• Signature errors like SignatureDoesNotMatch; those are credential or region problems.
• You are on boto3 below 1.36.0 and never enabled checksums.
• GetObject failures; the new defaults also validate on Get, but the fix path differs.

Compatibility

• boto3/botocore 1.36.0+ and s3transfer 0.11.0+: default integrity on.
• AWS SDK for Python only; other SDKs have their own timelines.

Variant phrasings

• XAmzContentSHA256Mismatch boto3
• boto3 1.36.0 S3 checksum failure
• S3 default integrity change PutObject fails
• disable boto3 S3 checksum validation

Why it happens

In 1.36.0 the S3 client started adding a checksum to every Put and validating checksums on Get by default. Anything that mutates the request body in flight (proxies, middleware) breaks the checksum match, and some older patterns that worked without checksums now fail.

Edge cases

• Disabling integrity globally is a security regression; scope it to the specific client or operation.
• Source: https://github.com/boto/boto3/issues/4392 and https://docs.aws.amazon.com/sdkref/latest/guide/feature-dataintegrity.html

In https://github.com/boto/boto3/issues/4392, the reporter asked: Issue boto/boto3#4392 (closed, 25 comments): In AWS SDK for Python v1.36.0, we released changes to the S3 client that adopts new default integrity protections. For more information on default integrity behavior, please refer to the official SDK documentation. In SDK releases from this version on, clients default to enabling an additional checksum on all Put calls and enabling validation on Get calls. You can disable default integrity protections for S3. The verified answer: After boto3 1.36.0 turned on default S3 integrity checksums, PutObject calls can fail with XAmzContentSHA256Mismatch: The Content-SHA256 you specified did not match what we received. If this blocks you, pin back to the previous minor line as a stopgap: boto3<1.36.0, botocore<1.36.0, s3transfer<0.11.0. Longer term, upgrade and keep the checksums on if you can (they protect S3 integrity), and only disable the default integrity behavior per the AWS docs if you have a specific reason. Source thread: https://github.com/boto/boto3/issues/4392