{"record":{"id":"e2e6a1ad2b95112f","repo":"boto/boto3","slug":"crt-transfer-client-is-configured-but-is-missing-m","errorCode":null,"errorMessage":"CRT transfer client is configured but is missing minimum crt version. CRT installed: {HAS_CRT}","messagePattern":"CRT transfer client is configured but is missing minimum crt version\\. CRT installed: (.+?)","errorType":"exception","errorClass":"MissingDependencyException","httpStatus":null,"severity":"error","filePath":"boto3/s3/transfer.py","lineNumber":209,"sourceCode":"\n\ndef _should_use_crt(config):\n    # This feature requires awscrt>=0.19.18\n    has_min_crt = HAS_CRT and has_minimum_crt_version((0, 19, 18))\n    is_optimized_instance = has_min_crt and awscrt.s3.is_optimized_for_system()\n    pref_transfer_client = config.preferred_transfer_client.lower()\n\n    if (\n        pref_transfer_client == constants.CRT_TRANSFER_CLIENT\n        and not has_min_crt\n    ):\n        msg = (\n            \"CRT transfer client is configured but is missing minimum CRT \"\n            f\"version. CRT installed: {HAS_CRT}\"\n        )\n        if HAS_CRT:\n            msg += f\", with version: {awscrt.__version__}\"\n        raise MissingDependencyException(msg=msg)\n\n    if (\n        is_optimized_instance\n        and pref_transfer_client == constants.AUTO_RESOLVE_TRANSFER_CLIENT\n    ) or pref_transfer_client == constants.CRT_TRANSFER_CLIENT:\n        logger.debug(\n            \"Attempting to use CRTTransferManager. Config settings may be ignored.\"\n        )\n        return True\n\n    logger.debug(\n        \"Opting out of CRT Transfer Manager. \"\n        \"Preferred client: %s, CRT available: %s, Instance Optimized: %s\",\n        pref_transfer_client,\n        HAS_CRT,\n        is_optimized_instance,\n    )\n    return False","sourceCodeStart":191,"sourceCodeEnd":227,"githubUrl":"https://github.com/boto/boto3/blob/6e10b029c1326a437932a8b24f38af69fd986e15/boto3/s3/transfer.py#L191-L227","documentation":"Raised by `_should_use_crt` when `TransferConfig.preferred_transfer_client` is set to `'crt'` but the optional `awscrt` package is either not installed or older than the required minimum (`0.19.18`). The CRT (AWS Common Runtime) transfer client is an optimized, optional backend for S3 transfers; boto3 falls back to the default manager only when the client is not explicitly requested. Raising as `MissingDependencyException` makes the absent optional dependency explicit.","triggerScenarios":"Constructing `S3Transfer`/`TransferConfig` with `preferred_transfer_client='crt'` (the constant `CRT_TRANSFER_CLIENT`) while `awscrt` is missing or `awscrt.__version__ < 0.19.18`. Triggered when the first transfer that evaluates the config is created.","commonSituations":"Enabling the CRT client after reading a performance guide but forgetting `pip install awscrt`; an environment where `awscrt` failed to install (platform/arch mismatch, e.g. some musl/older-glibc images); pinning an old `awscrt` from a lockfile; CI cache restoring a stale `awscrt`.","solutions":["Install or upgrade the CRT dependency: `pip install -U 'awscrt>=0.19.18'`.","If you do not actually need CRT, remove `preferred_transfer_client='crt'` from your TransferConfig so boto3 uses the default transfer manager.","Set `preferred_transfer_client='auto'` to let boto3 use CRT only when available and beneficial.","On platforms where `awscrt` has no wheel, build it from source (`pip install awscrt --no-binary :all:`) only if build toolchain is present; otherwise stay on the default client."],"exampleFix":"# before\nfrom boto3.s3.transfer import TransferConfig\ncfg = TransferConfig(preferred_transfer_client='crt')\ns3.download_file('b', 'k', '/tmp/k')  # MissingDependencyException if awscrt absent/old\n\n# after (option A: install the dependency)\n#   pip install -U 'awscrt>=0.19.18'\n# after (option B: drop the requirement)\ncfg = TransferConfig()  # default manager, no CRT needed","handlingStrategy":"validation","validationCode":"try:\n    import awscrt\n    from packaging.version import Version\n    assert Version(awscrt.__version__) >= Version('0.19.18'), 'awscrt too old'\n    HAS_MIN_CRT = True\nexcept ImportError:\n    HAS_MIN_CRT = False\n\nfrom boto3.s3.transfer import TransferConfig\ncfg = TransferConfig(preferred_transfer_client='crt') if HAS_MIN_CRT else TransferConfig()","typeGuard":"def crt_available(min_version=(0, 19, 18)) -> bool:\n    try:\n        import awscrt\n        parts = tuple(int(x) for x in awscrt.__version__.split('.')[:3])\n        return parts >= min_version\n    except Exception:\n        return False","tryCatchPattern":"from boto3.exceptions import MissingDependencyException\ntry:\n    s3.download_file(b, k, path, Config=TransferConfig(preferred_transfer_client='crt'))\nexcept MissingDependencyException:\n    s3.download_file(b, k, path)  # fall back to default transfer client","preventionTips":["Prefer preferred_transfer_client='auto' unless you specifically need CRT.","Add 'awscrt>=0.19.18' to requirements when you opt into CRT.","Verify awscrt imports in CI for your target platform."],"tags":["s3","transfer","crt","optional-dependency","version-mismatch"],"backgroundTag":null,"analyzedSha":"6e10b029c1326a437932a8b24f38af69fd986e15","analyzedAt":"2026-08-11T20:52:47.213Z","contentChangedAt":null,"schemaVersion":2},"datasetVersion":"2026-09-23T08:17:48.524Z"}