ValueError: 256 is not a valid ZoneType

[Bluscream]

Is this a HASS error or upstream?

Logger: homeassistant.components.openrgb.config_flow
Source: components/openrgb/config_flow.py:105
integration: openrgb (documentation, issues)
First occurred: 1:09:22 AM (1 occurrence)
Last logged: 1:09:22 AM

Unknown error while connecting to OpenRGB SDK server at 192.168.2.50:6742
Traceback (most recent call last):
  File "/usr/src/homeassistant/homeassistant/components/openrgb/config_flow.py", line 105, in async_step_user
    await validate_input(self.hass, host, port)
  File "/usr/src/homeassistant/homeassistant/components/openrgb/config_flow.py", line 43, in validate_input
    await hass.async_add_executor_job(_try_connect, host, port)
  File "/usr/local/lib/python3.14/concurrent/futures/thread.py", line 86, in run
    result = ctx.run(self.task)
  File "/usr/local/lib/python3.14/concurrent/futures/thread.py", line 73, in run
    return fn(*args, **kwargs)
  File "/usr/src/homeassistant/homeassistant/components/openrgb/config_flow.py", line 40, in _try_connect
    client = OpenRGBClient(host, port, DEFAULT_CLIENT_NAME)
  File "/usr/local/lib/python3.14/site-packages/openrgb/orgb.py", line 394, in __init__
    self.update()
    ~~~~~~~~~~~^^
  File "/usr/local/lib/python3.14/site-packages/openrgb/orgb.py", line 582, in update
    self.comms.requestDeviceNum()
    ~~~~~~~~~~~~~~~~~~~~~~~~~~~^^
  File "/usr/local/lib/python3.14/site-packages/openrgb/network.py", line 214, in requestDeviceNum
    self.read()
    ~~~~~~~~~^^
  File "/usr/local/lib/python3.14/site-packages/openrgb/network.py", line 116, in read
    self.callback(device_id, packet_type, buff[0])
    ~~~~~~~~~~~~~^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
  File "/usr/local/lib/python3.14/site-packages/openrgb/orgb.py", line 406, in _callback
    self.comms.requestDeviceData(x)
    ~~~~~~~~~~~~~~~~~~~~~~~~~~~~^^^
  File "/usr/local/lib/python3.14/site-packages/openrgb/network.py", line 207, in requestDeviceData
    self.read()
    ~~~~~~~~~^^
  File "/usr/local/lib/python3.14/site-packages/openrgb/network.py", line 137, in read
    self.callback(device_id, packet_type, utils.ControllerData.unpack(data, self._protocol_version))
                                          ~~~~~~~~~~~~~~~~~~~~~~~~~~~^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
  File "/usr/local/lib/python3.14/site-packages/openrgb/utils.py", line 603, in unpack
    zones = parse_list(ZoneData, data, version)
  File "/usr/local/lib/python3.14/site-packages/openrgb/utils.py", line 148, in parse_list
    things.append(kind.unpack(data, version, x))  # type: ignore
                  ~~~~~~~~~~~^^^^^^^^^^^^^^^^^^
  File "/usr/local/lib/python3.14/site-packages/openrgb/utils.py", line 485, in unpack
    segments = parse_list(SegmentData, data, version)
  File "/usr/local/lib/python3.14/site-packages/openrgb/utils.py", line 148, in parse_list
    things.append(kind.unpack(data, version, x))  # type: ignore
                  ~~~~~~~~~~~^^^^^^^^^^^^^^^^^^
  File "/usr/local/lib/python3.14/site-packages/openrgb/utils.py", line 399, in unpack
    segment_type = ZoneType(parse_var("i", data))
  File "/usr/local/lib/python3.14/enum.py", line 707, in __call__
    return cls.__new__(cls, value)
           ~~~~~~~~~~~^^^^^^^^^^^^
  File "/usr/local/lib/python3.14/enum.py", line 1192, in __new__
    raise ve_exc
ValueError: 256 is not a valid ZoneType

[septicwolf818]

@jath03 I made a small research on this issue

Symptom: connecting a recent OpenRGB server ( in my case release_candidate_1.0rc3+, SDK protocol 6) with openrgb-python 0.3.6 fails during device discovery with ValueError: 256 is not a valid ZoneType (or any garbage value), before any device can be controlled.

Cause: a wire-format mismatch introduced in the server, not an enum that merely grew.

The client negotiates down to protocol version 4 (OPENRGB_PROTOCOL_VERSION = 4 in network.py, server is at 6). On that wire, each zone is serialized as:

name(str), type(i), leds_min(I), leds_max(I), num_leds(I), matrix_zone_size(H)

and - when matrix_zone_size > 0 - followed by:

height(I), width(I), height*width LED-map entries (I each)

Newer OpenRGB servers (1.0rc3+, RGBController::GetZoneDescriptionData) now write the matrix-map block for every zone, regardless of zone type. For LINEAR/SINGLE zones the map is empty, so it still emits height=0, width=0 (8 bytes). The client's ZoneData.unpack (utils.py) only consumes that block when zone_type == ZoneType.MATRIX:

if zone_type == ZoneType.MATRIX:
    height = parse_var("I", data)
    width = parse_var("I", data)
    ...

For any non-MATRIX zone the parser stays 8 bytes behind, and from that point every subsequent field is garbage - which is why you see impossible values landing in zone_type and the ValueError.

Why it wasn't caught: the block is always guarded by matrix_zone_size, which is 0 when no map exists. So the parse can be made correct for both old and new servers by branching on the size field instead of the zone type.

My temp fix (client side monkey path in my app):

1. In ZoneData.unpack, consume the matrix block whenever matrix_zone_size > 0, not only when zone_type == ZoneType.MATRIX.
2. Widen the ZoneType enum to the current server values: SINGLE, LINEAR, MATRIX, LINEAR_LOOP, MATRIX_LOOP_X, MATRIX_LOOP_Y, SEGMENTED (0–6), and add a _missing_ fallback so a future new type degrades gracefully instead of crashing the loop.

[felipecrs]

That's likely an issue that should be reported and fixed in OpenRGB itself then.

[septicwolf818]

@felipecrs I have the fix ready here: #93

@jath03 I am waiting for your review.

[CalcProgrammer1]

See my comment on #93, on the OpenRGB client we check if matrix map size > 0, the check against zone type here is incorrect even for old protocol versions. It just so happened that zones with matrix type are the only zones with a valid matrix map so this logic ended up working, but officially the protocol has always allowed a matrix map on any type zone as the server does not correlate these two when sending the packet. With the next merge, every zone now has a matrix map as they are no longer pointer backed, but I will update OpenRGB to skip empty maps for backwards compat. There are some cases now where a zone may have a valid map but not be matrix type though.

[jath03]

Should be closed by #93 (please verify), but I'll leave this open until I make a new release, as I want to do a bit more testing myself and go through the rest of the issues first.