Zigbee2MQTT add-on won’t stay running unless socat block exists (even when disabled)

Configuration Zigbee
1

I’m posting this to save other users a lot of time — this issue looks like bad hardware, firmware, or USB problems, but it isn’t.

Symptoms

  • Zigbee2MQTT logs show:
    • Adapter detected
    • Coordinator starts
    • Backup written
  • Home Assistant UI:
    • Add-on flips back to :arrow_forward: Start
    • CPU/RAM briefly appears, then disappears
    • Looks like it “isn’t running”
  • Config edits:
    • Some keys are silently removed on Save
    • No clear validation error shown

This led me (wrongly) to suspect:

  • Bad dongle
  • Firmware incompatibility
  • ZBT-2 vs Sonoff issue
  • Mosquitto problem

Root cause

The HA Zigbee2MQTT add-on requires a socat: block to exist, even when socat is disabled.

If socat: is missing entirely:

  • Config saves
  • Zigbee2MQTT starts briefly
  • Then exits cleanly (not a crash)
  • HA UI flips back to :arrow_forward: Start

Because it’s a clean shutdown, it’s very misleading.

Working minimal config

This works reliably:

data_path: /config/zigbee2mqtt

socat:
  enabled: false
  master: pty,raw,echo=0,link=/tmp/ttyZ2M,mode=777
  slave: tcp-listen:8485,keepalive,nodelay,reuseaddr
  options: "-d -d"
  log: false

mqtt:
  server: mqtt://core-mosquitto

serial:
  port: /dev/ttyUSB0
  adapter: zstack
  baudrate: 115200

Once this was in place:

  • Add-on stayed running
  • UI state matched reality
  • Both ZBT-2 and Sonoff Zigbee 3.0 USB Dongle Plus worked fine

Environment

  • Home Assistant Green
  • HA OS
  • Zigbee2MQTT add-on 2.7.x
  • Mosquitto add-on (default config)
  • Dongles tested:
    • Nabu Casa ZBT-2
    • Sonoff Zigbee 3.0 USB Dongle Plus

Why posting this

The failure mode looks exactly like:

  • bad hardware
  • firmware mismatch
  • USB instability

It’s actually a config schema / validation gotcha.

Hopefully this saves someone else a weekend :slightly_smiling_face:

1 Like