boto/boto3 · error · InvalidCrtTransferConfigError

The following transfer config options are invalid when prefe

Error message

The following transfer config options are invalid when preferred_transfer_client is set to crt: {invalid_crt_args}`

What it means

Raised by _validate_crt_transfer_config() in boto3/crt.py when a TransferConfig has preferred_transfer_client='crt' but also sets options outside the CRT allowlist (_ALLOWED_CRT_TRANSFER_CONFIG_OPTIONS = multipart_threshold, max_concurrency, max_request_concurrency, multipart_chunksize, preferred_transfer_client). The CRT (AWS Common Runtime) transfer manager only honors a subset of the classic S3 transfer config; setting incompatible options such as max_bandwidth, num_download_attempts, max_io_queue, io_chunksize, or use_threads is rejected so the user does not silently lose configuration. Validation runs only when preferred_transfer_client is explicitly 'crt' (not 'auto').

Source

Thrown at boto3/crt.py:193

def _validate_crt_transfer_config(config):
    if config is None:
        return
    # CRT client can also be configured via `AUTO_RESOLVE_TRANSFER_CLIENT`
    # but it predates this validation. We only validate against CRT client
    # configured via `CRT_TRANSFER_CLIENT` to preserve compatibility.
    if config.preferred_transfer_client != CRT_TRANSFER_CLIENT:
        return
    invalid_crt_args = []
    for param in config.DEFAULTS.keys():
        val = config.get_deep_attr(param)
        if (
            param not in _ALLOWED_CRT_TRANSFER_CONFIG_OPTIONS
            and val is not config.UNSET_DEFAULT
        ):
            invalid_crt_args.append(param)
    if len(invalid_crt_args) > 0:
        raise InvalidCrtTransferConfigError(
            "The following transfer config options are invalid "
            "when preferred_transfer_client is set to crt: "
            f"{', '.join(invalid_crt_args)}`"
        )


def create_crt_transfer_manager(client, config):
    """Create a CRTTransferManager for optimized data transfer."""
    crt_s3_client = get_crt_s3_client(client, config)
    if is_crt_compatible_request(client, crt_s3_client):
        crt_transfer_manager_kwargs = {
            'crt_s3_client': crt_s3_client.crt_client,
            'crt_request_serializer': BOTOCORE_CRT_SERIALIZER,
        }
        if TRANSFER_CONFIG_SUPPORTS_CRT:
            _validate_crt_transfer_config(config)
            crt_transfer_manager_kwargs['config'] = config
        if not TRANSFER_CONFIG_SUPPORTS_CRT and config:

View on GitHub (pinned to c7b4afac23)

Solutions

1. Remove the disallowed option(s) listed in the error message from your TransferConfig call.
2. If you need classic-only options like max_bandwidth or num_download_attempts, set preferred_transfer_client='classic' instead of 'crt'.
3. Use preferred_transfer_client='auto' so boto3 picks CRT when available and silently falls back to classic, validating config only in pure-CRT mode.
4. Keep only allowed CRT options: multipart_threshold, max_concurrency, multipart_chunksize, preferred_transfer_client.

Example fix

# before
config = TransferConfig(
    preferred_transfer_client='crt',
    max_bandwidth=1024,
    num_download_attempts=10,
)
client.upload_file('f', 'b', 'k', Config=config)

# after
config = TransferConfig(
    preferred_transfer_client='crt',
    multipart_threshold=16 * 1024 * 1024,
    max_concurrency=20,
)
client.upload_file('f', 'b', 'k', Config=config)

from boto3.crt import _ALLOWED_CRT_TRANSFER_CONFIG_OPTIONS

def safe_crt_config(**kwargs):
    bad = set(kwargs) - _ALLOWED_CRT_TRANSFER_CONFIG_OPTIONS
    if bad:
        raise ValueError(f'Not CRT-compatible: {bad}')
    from boto3.s3.transfer import TransferConfig
    return TransferConfig(preferred_transfer_client='crt', **kwargs)

from boto3.exceptions import InvalidCrtTransferConfigError
try:
    create_transfer_manager(client, config)
except InvalidCrtTransferConfigError as e:
    # strip disallowed options and retry, or fall back to classic
    config.preferred_transfer_client = 'classic'
    create_transfer_manager(client, config)

When it happens

Trigger: Call create_transfer_manager(client, config) or perform any S3 upload/download/copy via the high-level transfer API while config = TransferConfig(preferred_transfer_client='crt', max_bandwidth=1024) (or any other disallowed option). The validation iterates config.DEFAULTS and flags any key whose value differs from UNSET_DEFAULT but is not in the allowlist.

Common situations: Reusing a TransferConfig that previously worked with the classic/default client after flipping preferred_transfer_client to 'crt'; migrating S3 transfer code to CRT for performance without pruning classic-only knobs; upgrading boto3/s3transer where CRT config validation was newly introduced.

Related errors

• Either a boto3.Client or s3transfer.manager.TransferManager
• Manager cannot be provided with client, config, nor osutil.
• Fileobj must implement read
• Fileobj must implement write
• CRT transfer client is configured but is missing minimum crt

AI-assisted analysis of boto/boto3@c7b4afac23 (2026-08-04). Data as JSON: /data/errors/600f47727fc1ff3d.json. Report an issue: GitHub.