{"record":{"id":"dbd4be1f50262ebf","repo":"jax-ml/jax","slug":"from-dlpack-can-only-unpack-a-dlpack-tensor-onto-a","errorCode":null,"errorMessage":"from_dlpack can only unpack a dlpack tensor onto a singular device, but a Sharding with {len(device_set)} devices was provided.","messagePattern":"from_dlpack can only unpack a dlpack tensor onto a singular device, but a Sharding with (.+?) devices was provided\\.","errorType":"validation","errorClass":"ValueError","httpStatus":null,"severity":"error","filePath":"jax/_src/dlpack.py","lineNumber":236,"sourceCode":"      If ``copy=True`` then a copy is always performed, even if unpacked onto\n      the same device. If ``copy=False`` then the copy is never performed and\n      will raise an error if necessary. When ``copy=None`` then a copy may be\n      performed if needed for a device transfer.\n\n  Returns:\n    A jax.Array\n\n  Note:\n    While JAX arrays are always immutable, dlpack buffers cannot be marked as\n    immutable, and it is possible for processes external to JAX to mutate them\n    in-place. If a jax Array is constructed from a dlpack buffer and the buffer\n    is later modified in-place, it may lead to undefined behavior when using\n    the associated JAX array.\n  \"\"\"\n  if isinstance(device, Sharding):\n    device_set = device.device_set\n    if len(device_set) > 1:\n      raise ValueError(\n        \"from_dlpack can only unpack a dlpack tensor onto a singular device, but \"\n        f\"a Sharding with {len(device_set)} devices was provided.\"\n      )\n    device, = device_set\n  if not hasattr(external_array, \"__dlpack__\") or not hasattr(external_array, \"__dlpack_device__\"):\n    raise TypeError(\n        \"The array passed to from_dlpack must have __dlpack__ and __dlpack_device__ methods.\"\n    )\n\n  dl_device_type, device_id = external_array.__dlpack_device__()\n  try:\n    dl_device_platform = _DL_DEVICE_TO_PLATFORM[dl_device_type]\n  except KeyError:\n    raise TypeError(\n        \"Array passed to from_dlpack is on unsupported device type \"\n        f\"(DLDeviceType: {dl_device_type}, array: {external_array}\"\n    ) from None\n","sourceCodeStart":218,"sourceCodeEnd":254,"githubUrl":"https://github.com/jax-ml/jax/blob/1e1c6a8fc06dfcd1247076ec5cae4640cea5d7bb/jax/_src/dlpack.py#L218-L254","documentation":"from_dlpack can place a DLPack buffer on exactly one device; passing a multi-device Sharding (e.g. a NamedSharding or PmapSharding over several devices) is ambiguous and rejected.","triggerScenarios":"jax.dlpack.from_dlpack(external, device=jax.sharding.NamedSharding(mesh, P)) where the sharding's device_set has more than one device.","commonSituations":"Reusing sharding objects from a jitted multi-device pipeline as the device argument for interop imports.","solutions":["Pass a single Device (e.g. jax.devices()[0]) and shard afterwards with jax.device_put(arr, sharding)","Use a single-device sharding (device_set of size 1)","Import the array first, then redistribute with device_put(arr, desired_sharding)"],"exampleFix":"# before\njax.dlpack.from_dlpack(t, device=multi_device_sharding)\n\n# after\narr = jax.dlpack.from_dlpack(t, device=jax.devices()[0])\narr = jax.device_put(arr, multi_device_sharding)","handlingStrategy":"validation","validationCode":"if isinstance(device, jax.sharding.Sharding):\n    assert len(device.device_set) == 1, 'use a single device for from_dlpack'\n    device, = device.device_set","typeGuard":"import jax.sharding as sh\ndef is_single_device_sharding(s) -> bool:\n    return isinstance(s, sh.Sharding) and len(s.device_set) == 1","tryCatchPattern":"try:\n    jax.dlpack.from_dlpack(t, device=dev)\nexcept ValueError as e:\n    if 'singular device' not in str(e): raise\n    arr = jax.dlpack.from_dlpack(t); arr = jax.device_put(arr, dev)","preventionTips":["Pass Device objects to from_dlpack; shard with device_put afterwards"],"tags":["jax","dlpack","sharding","multi-device"],"backgroundTag":"invalid-device-argument","analyzedSha":"1e1c6a8fc06dfcd1247076ec5cae4640cea5d7bb","analyzedAt":"2026-08-27T09:53:25.647Z","schemaVersion":2},"datasetVersion":"2026-08-27T13:17:12.746Z"}