{"record":{"id":"1528278d66e4138f","repo":"sgl-project/sglang","slug":"invalid-cuda-handle-type-value-handle-type-value","errorCode":null,"errorMessage":"invalid CUDA handle-type value: {handle_type_value}","messagePattern":"invalid CUDA handle-type value: (.+?)","errorType":"validation","errorClass":"ValueError","httpStatus":null,"severity":"error","filePath":"python/sglang/srt/utils/cuda_vmm_utils.py","lineNumber":297,"sourceCode":"    elif handle_types is None:\n        handle_types = drv.CUmemAllocationHandleType.CU_MEM_HANDLE_TYPE_NONE\n    elif not isinstance(handle_types, int):\n        raise ValueError(\"handle_types must be 'auto', an integer, or None\")\n\n    handle_type_value = int(handle_types)\n    valid_handle_types = {\n        int(drv.CUmemAllocationHandleType.CU_MEM_HANDLE_TYPE_NONE): (\n            drv.CUmemAllocationHandleType.CU_MEM_HANDLE_TYPE_NONE\n        ),\n        int(drv.CUmemAllocationHandleType.CU_MEM_HANDLE_TYPE_POSIX_FILE_DESCRIPTOR): (\n            drv.CUmemAllocationHandleType.CU_MEM_HANDLE_TYPE_POSIX_FILE_DESCRIPTOR\n        ),\n        int(drv.CUmemAllocationHandleType.CU_MEM_HANDLE_TYPE_FABRIC): (\n            drv.CUmemAllocationHandleType.CU_MEM_HANDLE_TYPE_FABRIC\n        ),\n    }\n    if handle_type_value not in valid_handle_types:\n        raise ValueError(f\"invalid CUDA handle-type value: {handle_type_value}\")\n\n    prop = drv.CUmemAllocationProp()\n    prop.type = drv.CUmemAllocationType.CU_MEM_ALLOCATION_TYPE_PINNED\n    prop.location.type = drv.CUmemLocationType.CU_MEM_LOCATION_TYPE_DEVICE\n    prop.location.id = int(device_id)\n    # cuda-bindings 13.0.x requires the generated enum here; newer releases\n    # also accept a plain int, which previously hid this compatibility issue.\n    prop.requestedHandleTypes = valid_handle_types[handle_type_value]\n    prop.allocFlags.gpuDirectRDMACapable = int(gpu_direct_rdma)\n    return prop\n\n\ndef get_allocation_granularity(prop, flag=_RECOMMENDED_GRANULARITY) -> int:\n    \"\"\"Return allocation granularity for a CUDA policy flag.\"\"\"\n    drv = _get_cuda_driver()\n    return int(\n        check_drv(\n            drv.cuMemGetAllocationGranularity(prop, flag),","sourceCodeStart":279,"sourceCodeEnd":315,"githubUrl":"https://github.com/sgl-project/sglang/blob/0132848349585cfe6aae51c4941cbae872505f8a/python/sglang/srt/utils/cuda_vmm_utils.py#L279-L315","documentation":"After normalizing handle_types to an integer, the value is checked against the known set (NONE, POSIX, FABRIC, and whatever the installed bindings define). An integer outside this set — a stale bitmask, wrong combination, or typo'd constant — is rejected before building the CUmemAllocationProp.","triggerScenarios":"Passing a bitmask from a different CUDA version that includes bits the installed cuda-bindings doesn't define; computing handle types with bitwise-OR of deprecated flags; hardcoding a magic number.","commonSituations":"Code written against a newer/older CUDA header reused with different cuda-python version; OR-ing FABRIC and POSIX which may yield an unsupported combined value on some versions.","solutions":["Use int(drv.CUmemAllocationHandleType.CU_MEM_HANDLE_TYPE_POSIX) (or the auto path) instead of magic numbers","Upgrade/downgrade cuda-python so its handle-type enum matches the constants you compute","Validate the bitmask against the installed bindings' enum values before calling"],"exampleFix":"# before\nmake_device_allocation_prop(0, handle_types=0x03)  # stale bitmask\n\n# after\nmake_device_allocation_prop(0, handle_types='auto')","handlingStrategy":"validation","validationCode":"drv = _get_cuda_driver()\nvalid = {int(v) for k, v in vars(drv.CUmemAllocationHandleType).items() if k.startswith('CU_MEM_HANDLE_TYPE')}\nassert int(handle_types) in valid","typeGuard":"def is_known_handle_type_value(value: int) -> bool:\n    drv = _get_cuda_driver()\n    return value in {\n        int(drv.CUmemAllocationHandleType.CU_MEM_HANDLE_TYPE_NONE),\n        int(drv.CUmemAllocationHandleType.CU_MEM_HANDLE_TYPE_POSIX),\n        int(drv.CUmemAllocationHandleType.CU_MEM_HANDLE_TYPE_FABRIC),\n    }","tryCatchPattern":null,"preventionTips":["Never pass magic bitmask numbers; use enum constants via int()","Pin cuda-python version consistent with the driver in use"],"tags":["cuda","vmm","validation","handle","enum-value"],"backgroundTag":"invalid-enum-value","analyzedSha":"0132848349585cfe6aae51c4941cbae872505f8a","analyzedAt":"2026-08-28T05:10:05.995Z","schemaVersion":2},"datasetVersion":"2026-08-28T06:17:29.519Z"}