deepset-ai/haystack · error · ValueError

Unknown device type string '{string}'

Error message

Unknown device type string '{string}'

What it means

DeviceType.from_str raises ValueError when the string passed does not match any DeviceType value ('cpu', 'cuda', 'mps', 'xpu', 'disk'). Device strings must be exactly one of the known device type identifiers.

Source

Thrown at haystack/utils/device.py:50

    XPU = "xpu"

    def __str__(self) -> str:
        return self.value

    @staticmethod
    def from_str(string: str) -> "DeviceType":
        """
        Create a device type from a string.

        :param string:
            The string to convert.
        :returns:
            The device type.
        """
        mapping = {e.value: e for e in DeviceType}
        _type = mapping.get(string)
        if _type is None:
            raise ValueError(f"Unknown device type string '{string}'")
        return _type


@dataclass
class Device:
    """
    A generic representation of a device.

    :param type:
        The device type.
    :param id:
        The optional device id.
    """

    type: DeviceType
    id: int | None = field(default=None)

    def __init__(self, type: DeviceType, id: int | None = None) -> None:  # noqa:A002

View on GitHub (pinned to e318778c9b)

Solutions

1. Use one of the exact supported strings: 'cpu', 'cuda', 'mps', 'xpu', 'disk'
2. Strip the device index from inputs like 'cuda:0' — pass type 'cuda' and id 0 to Device(type, id)
3. Check DeviceType enum values (haystack.utils.device.DeviceType) for the list supported by your version
4. Upgrade Haystack if you need a newer device type

Example fix

// before
dev = DeviceType.from_str("cuda:0")
// after
from haystack.utils.device import Device, DeviceType
dev = Device(DeviceType.from_str("cuda"), 0)  # or Device.from_str("cuda:0")

VALID = {"cpu", "cuda", "mps", "xpu", "disk"}
def is_valid_device_string(s: str) -> bool:
    return s.lower() in VALID
# for indexed strings use Device.from_str which splits type/id

def is_device_type_str(s: object) -> bool:
    return isinstance(s, str) and s.lower() in {"cpu", "cuda", "mps", "xpu", "disk"}

try:
    dtype = DeviceType.from_str(s)
except ValueError as e:
    print(f"{s!r} is not a supported device type; use cpu/cuda/mps/xpu/disk")
    dtype = DeviceType.CPU

When it happens

Trigger: Calling DeviceType.from_str with a misspelled or unsupported string ('gpu', 'CPU', 'cuda:0' — the id must be stripped, 'cuda0'), or indirectly via Device.from_str/ComponentDevice.from_str and HF device map conversion with unrecognized device names.

Common situations: Users writing 'gpu' in pipeline config where 'cuda' is required; passing 'cuda:0' instead of separating type and id; hardware-specific devices (e.g. 'npu') unsupported by this Haystack version.

Related errors

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

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