Resolving Boto3 Checksum Issue with S3-Compatible Services

When using the Boto3 library with S3-compatible services e.g. Blackblaze B2, you might encounter the error: Unsupported header 'x-amz-checksum-mode' received for this API call

This happens because Boto3, by default, enables checksum validation specifically for Amazon S3. However, third-party providers like Backblaze B2 may not support certain checksum headers.

Backblaze B2’s documentation ¹ lists unsupported checksum features, such as:

• x-amz-checksum-crc32
• x-amz-checksum-crc32c
• x-amz-checksum-crc64nvme
• x-amz-checksum-sha1
• x-amz-checksum-sha256
• x-amz-checksum-algorithm
• x-amz-checksum-mode

To disable checksum validation in Boto3, you need to adjust the client configuration. The boto3 client can be constructed with the following settings:

Solution

The Boto3 configuration options request_checksum_calculation and response_checksum_validation control checksum handling ². Both options accept values:

• when_supported
• when_required

To disable checksum validation, set both options to when_required.

Final Code for Backblaze B2:

import boto3
from botocore.config import Config

session = boto3.Session(
    aws_access_key_id="<ACCESS_KEY_ID>",
    aws_secret_access_key="<SECRET_ACCESS_KEY>",
)

s3_client = session.client(
    "s3",
    endpoint_url="<BLACKBLAZE_ENDPOINT_URL>",
    config=Config(
        response_checksum_validation="when_required",
        request_checksum_calculation="when_required",
    ),
)

This will ensure that the checksum validation is disabled while using Backblaze B2 with Boto3.