deepset-ai/haystack · error · ValueError

Only single devices can be converted to spaCy format

Error message

Only single devices can be converted to spaCy format

What it means

ComponentDevice.to_spacy raises ValueError when the component is not a single device; spaCy's device API (a GPU ordinal int, -1 for CPU) cannot express a multi-device map.

Source

Thrown at haystack/utils/device.py:358

        if self._single_device is None:
            raise ValueError("Only single devices can be converted to PyTorch format")

        assert self._single_device is not None
        return str(self._single_device)

    def to_spacy(self) -> int:
        """
        Convert the component device representation to spaCy format.

        Device maps are not supported.

        :returns:
            The spaCy device representation.
        """
        self._validate()

        if self._single_device is None:
            raise ValueError("Only single devices can be converted to spaCy format")

        assert self._single_device is not None
        if self._single_device.type == DeviceType.GPU:
            assert self._single_device.id is not None
            return self._single_device.id
        return -1

    def to_hf(self) -> int | str | dict[str, int | str]:
        """
        Convert the component device representation to HuggingFace format.

        :returns:
            The HuggingFace device representation.
        """
        self._validate()

        def convert_device(device: Device, *, gpu_id_only: bool = False) -> int | str:
            if gpu_id_only and device.type == DeviceType.GPU:

View on GitHub (pinned to e318778c9b)

Solutions

1. Use to_spacy only on single-device components; guard with has_multiple_devices()
2. Pick one concrete device from the DeviceMap and build ComponentDevice.from_single(Device(...)) for the spaCy component
3. Configure the spaCy portion to CPU (-1) when the pipeline is multi-device

Example fix

// before
spacy_dev = comp.to_spacy()  # multi-device -> raises
// after
if comp.has_multiple_devices():
    spacy_dev = -1  # spaCy cannot use multiple devices; fall back to CPU
else:
    spacy_dev = comp.to_spacy()

def spacy_device_or_cpu(comp: ComponentDevice) -> int:
    return comp.to_spacy() if not comp.has_multiple_devices() else -1

def supports_spacy_conversion(comp: ComponentDevice) -> bool:
    return comp._single_device is not None

try:
    gpu_id = comp.to_spacy()
except ValueError:
    gpu_id = -1  # spaCy: -1 means CPU

When it happens

Trigger: Calling to_spacy() on a ComponentDevice holding a DeviceMap (from_multiple/from_hf).

Common situations: Bridging Haystack device config into spaCy-based components (e.g. tokenization/embedding) while the pipeline is configured for multi-GPU sharding.

Related errors

• Only single devices can be converted to PyTorch format
• Unknown device type string '{string}'
• Device id must be >= 0, got {id}
• The disk device can only be used as a part of device maps
• The component device can neither be empty nor contain both a

AI-assisted analysis of deepset-ai/haystack@e318778c9b (2026-08-30). Data as JSON: /api/errors/7c5c7876fa33f2fe. Report an issue: GitHub.