{"id":"600f47727fc1ff3d","repo":"boto/boto3","slug":"the-following-transfer-config-options-are-invalid","errorCode":null,"errorMessage":"The following transfer config options are invalid when preferred_transfer_client is set to crt: {invalid_crt_args}`","messagePattern":"The following transfer config options are invalid when preferred_transfer_client is set to crt: (.+?)`","errorType":"validation","errorClass":"InvalidCrtTransferConfigError","httpStatus":null,"severity":"error","filePath":"boto3/crt.py","lineNumber":193,"sourceCode":"\ndef _validate_crt_transfer_config(config):\n    if config is None:\n        return\n    # CRT client can also be configured via `AUTO_RESOLVE_TRANSFER_CLIENT`\n    # but it predates this validation. We only validate against CRT client\n    # configured via `CRT_TRANSFER_CLIENT` to preserve compatibility.\n    if config.preferred_transfer_client != CRT_TRANSFER_CLIENT:\n        return\n    invalid_crt_args = []\n    for param in config.DEFAULTS.keys():\n        val = config.get_deep_attr(param)\n        if (\n            param not in _ALLOWED_CRT_TRANSFER_CONFIG_OPTIONS\n            and val is not config.UNSET_DEFAULT\n        ):\n            invalid_crt_args.append(param)\n    if len(invalid_crt_args) > 0:\n        raise InvalidCrtTransferConfigError(\n            \"The following transfer config options are invalid \"\n            \"when preferred_transfer_client is set to crt: \"\n            f\"{', '.join(invalid_crt_args)}`\"\n        )\n\n\ndef create_crt_transfer_manager(client, config):\n    \"\"\"Create a CRTTransferManager for optimized data transfer.\"\"\"\n    crt_s3_client = get_crt_s3_client(client, config)\n    if is_crt_compatible_request(client, crt_s3_client):\n        crt_transfer_manager_kwargs = {\n            'crt_s3_client': crt_s3_client.crt_client,\n            'crt_request_serializer': BOTOCORE_CRT_SERIALIZER,\n        }\n        if TRANSFER_CONFIG_SUPPORTS_CRT:\n            _validate_crt_transfer_config(config)\n            crt_transfer_manager_kwargs['config'] = config\n        if not TRANSFER_CONFIG_SUPPORTS_CRT and config:","sourceCodeStart":175,"sourceCodeEnd":211,"githubUrl":"https://github.com/boto/boto3/blob/c7b4afac237b976d48395d7523eaf7cec3a450b3/boto3/crt.py#L175-L211","documentation":"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').","triggerScenarios":"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.","commonSituations":"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.","solutions":["Remove the disallowed option(s) listed in the error message from your TransferConfig call.","If you need classic-only options like max_bandwidth or num_download_attempts, set preferred_transfer_client='classic' instead of 'crt'.","Use preferred_transfer_client='auto' so boto3 picks CRT when available and silently falls back to classic, validating config only in pure-CRT mode.","Keep only allowed CRT options: multipart_threshold, max_concurrency, multipart_chunksize, preferred_transfer_client."],"exampleFix":"# before\nconfig = TransferConfig(\n    preferred_transfer_client='crt',\n    max_bandwidth=1024,\n    num_download_attempts=10,\n)\nclient.upload_file('f', 'b', 'k', Config=config)\n\n# after\nconfig = TransferConfig(\n    preferred_transfer_client='crt',\n    multipart_threshold=16 * 1024 * 1024,\n    max_concurrency=20,\n)\nclient.upload_file('f', 'b', 'k', Config=config)","handlingStrategy":"validation","validationCode":"from boto3.crt import _ALLOWED_CRT_TRANSFER_CONFIG_OPTIONS\n\ndef safe_crt_config(**kwargs):\n    bad = set(kwargs) - _ALLOWED_CRT_TRANSFER_CONFIG_OPTIONS\n    if bad:\n        raise ValueError(f'Not CRT-compatible: {bad}')\n    from boto3.s3.transfer import TransferConfig\n    return TransferConfig(preferred_transfer_client='crt', **kwargs)","typeGuard":null,"tryCatchPattern":"from boto3.exceptions import InvalidCrtTransferConfigError\ntry:\n    create_transfer_manager(client, config)\nexcept InvalidCrtTransferConfigError as e:\n    # strip disallowed options and retry, or fall back to classic\n    config.preferred_transfer_client = 'classic'\n    create_transfer_manager(client, config)","preventionTips":["Build CRT configs through a factory function that filters against _ALLOWED_CRT_TRANSFER_CONFIG_OPTIONS.","Prefer preferred_transfer_client='auto' unless you specifically need the hard CRT guarantee.","Unit-test your TransferConfig construction with CRT mode enabled."],"tags":["s3","crt","transfer","config","validation"],"analyzedSha":"c7b4afac237b976d48395d7523eaf7cec3a450b3","analyzedAt":"2026-08-04T20:35:51.598Z","schemaVersion":2}