Switch cluster events from MOES gateway fail to decode: expected chip.tlv.uint, got int

[kipax]

Description

Switch cluster (cluster 59) events from MOES Matter Wired Gateway sub-devices fail to decode on both the stable Python Matter Server and the matter.js beta. Button press events (InitialPress, ShortRelease, MultiPressComplete) are received but dropped due to a type mismatch in the TLV decoder.

Environment

• Home Assistant: 2026.4.1
• Home Assistant OS: 17.2 (aarch64 / raspberrypi5-64)
• Matter Server Add-on: 8.4.0
• Matter SDK Wheels: tested with both 2025.7.0 (bundled) and 2024.11.4 (pinned)
• Gateway: MOES Matter Wired Gateway (Tuya-based, Zigbee sub-devices bridged to Matter)
• Affected devices: Tuya wireless scene switches (1GangSwitchAndScene, 4 Scene Switch) connected via MOES gateway

Error (Python Matter Server - stable)

ERROR [chip.clusters.Attribute] Error convering TLV to Cluster Object for path: Endpoint = None/Cluster = 59/Event = 1
ERROR [chip.clusters.Attribute] Failed Cluster Object: <class 'chip.clusters.Objects.Switch.Events.InitialPress'>
ERROR [chip.clusters.Attribute] Failed to decode field .newPosition, expected type <class 'chip.tlv.uint'>, got <class 'int'>

ERROR [chip.clusters.Attribute] Error convering TLV to Cluster Object for path: Endpoint = None/Cluster = 59/Event = 3
ERROR [chip.clusters.Attribute] Failed Cluster Object: <class 'chip.clusters.Objects.Switch.Events.ShortRelease'>
ERROR [chip.clusters.Attribute] Failed to decode field .previousPosition, expected type <class 'chip.tlv.uint'>, got <class 'int'>

ERROR [chip.clusters.Attribute] Error convering TLV to Cluster Object for path: Endpoint = None/Cluster = 59/Event = 6
ERROR [chip.clusters.Attribute] Failed Cluster Object: <class 'chip.clusters.Objects.Switch.Events.MultiPressComplete'>
ERROR [chip.clusters.Attribute] Failed to decode field .previousPosition, expected type <class 'chip.tlv.uint'>, got <class 'int'>

Error (matter.js beta)

ERROR EventDataDecoder Error decoding event 124/59/1: Unexpected type 0, was expecting 4.
ERROR EventDataDecoder Error decoding event 124/59/3: Unexpected type 0, was expecting 4.
ERROR EventDataDecoder Error decoding event 124/59/6: Unexpected type 0, was expecting 4.

Expected Behavior

Button press events (InitialPress event=1, ShortRelease event=3, MultiPressComplete event=6) from Switch cluster 59 should be decoded successfully and forwarded to Home Assistant as event entities, allowing automations to trigger on button presses.

Actual Behavior

Events are received from the MOES gateway but the TLV decoder rejects them because the newPosition and previousPosition fields are encoded as Python int instead of chip.tlv.uint. The events are silently dropped and never reach Home Assistant.

Root Cause

The MOES gateway encodes the position fields as a standard integer (TLV type 0) instead of the unsigned integer type (TLV type 4) expected by the Matter specification. The SDK decoder performs a strict type check and rejects the value.

Suggested Fix

The decoder should accept int as a valid value for uint fields, since they are semantically compatible. A lenient type coercion (e.g., int → uint) would resolve this for all devices with this firmware behavior.

Notes

• This was working in earlier versions of HA (pre-2026.4.x) — the MOES gateway firmware may have updated during a factory reset, or the SDK previously handled this more leniently
• Affects all Tuya/MOES Zigbee sub-devices that send Switch cluster events through the Matter bridge
• The gateway itself and all other functionality (on/off switches, sensors) work correctly — only event decoding is affected

[kipax]

Update: Partial fix found for matter.js beta

I was able to patch the TLV type check in the matter.js beta's TlvNumber.js to accept signed int (type 0) where unsigned int (type 4) is expected. This eliminates the EventDataDecoder errors completely.

Patch applied

File: @matter/types/dist/esm/tlv/TlvNumber.js

Changed:

if (typeLength.type !== this.type)

To:

if (typeLength.type !== this.type && !((this.type === 4 && typeLength.type === 0) || (this.type === 0 && typeLength.type === 4)))

Result

• TLV decode errors eliminated — no more Error decoding event X/59/Y: Unexpected type 0, was expecting 4
• BUT: events still don't propagate to Home Assistant event entities
• The EventDataDecoder in matter.js may have a second issue where decoded events are dropped before reaching the HA websocket, possibly because the event data structure doesn't match what HA expects after the type coercion

Method

Used NODE_OPTIONS=--require /config/matter_tlv_patch.js via the add-on's matter_server_env_vars option to file-patch TlvNumber.js on startup before the server loads it.

Request

Could you check if there's a second layer in the EventDataDecoder.ts or the WebSocket event forwarding that drops decoded Switch cluster events even after the TLV type issue is resolved?