A device shows up fine in Zigbee2MQTT — entities populated, everything reporting — and then it’s “unsupported” or missing half its entities under ZHA. Or the reverse: solid in ZHA, a ghost in Zigbee2MQTT until someone writes a custom converter for it. Neither platform is broken. They’re solving the same problem with two separate, hand-maintained databases, and support parity between them was never guaranteed in the first place.
This isn’t a platform-recommendation piece. It’s the mechanism underneath: what a ZHA quirk actually is, what a Zigbee2MQTT converter actually is, why they don’t share a codebase even though they do the same job, and what it means that newer ZHA quirks are now explicitly built by referencing existing Zigbee2MQTT converters as source material. If you’re choosing between the two platforms generally, our ZHA vs Zigbee2MQTT comparison covers that broader decision — this piece is the layer underneath it.
The short answer — same job, different codebase
Both a ZHA “quirk” and a Zigbee2MQTT converter exist to fix the same underlying problem: a Zigbee device manufacturer shipped firmware that deviates from the Zigbee Cluster Library (ZCL) specification, and without a translation layer, the platform either misreads the device’s data or can’t expose it at all. The Home Assistant community itself has described the two mechanisms as “basically the same” concept, just implemented for different integrations.
“Quirk” is ZHA’s term (from the underlying zigpy/zha-device-handlers library). “Converter” is Zigbee2MQTT’s term (from the zigbee-herdsman-converters package, formerly zigbee-shepherd converters). Different vocabulary, same category of fix.
What they are not is portable. A quirk is Python code written against zigpy’s internals. A converter is JavaScript/TypeScript written against zigbee-herdsman’s internals. Neither platform can load the other’s file. Support for a given device on Zigbee2MQTT tells you nothing certain about whether a ZHA quirk exists for it, and vice versa — the two databases are maintained independently, by different (if overlapping) contributor communities, on different release schedules.
What a ZHA quirk actually does
A ZHA quirk is a piece of code in the zha-device-handlers repository that intercepts a specific device’s non-standard Zigbee messages and remaps them into something ZCL-compliant that ZHA’s core can understand. Per the zha-device-handlers repository’s own description, quirks exist specifically to bridge the gap created when a manufacturer’s firmware doesn’t follow the ZCL spec correctly — wrong cluster IDs, nonstandard attribute reporting, vendor-specific clusters that need custom parsing.
Practically: if a device “just works” on ZHA with full entities and no oddities, it’s either fully ZCL-compliant firmware (rare among budget Zigbee hardware) or someone already wrote and merged a quirk for it. If it pairs but comes in with missing entities, wrong units, or an “unsupported” flag, no matching quirk exists yet — the device’s non-standard behavior is going un-translated.
What a Zigbee2MQTT converter actually does
A Zigbee2MQTT converter — sourced from the zigbee-herdsman-converters package — does the equivalent job for the Zigbee2MQTT/zigbee-herdsman stack: it defines how to interpret a specific device’s messages and exposes the result as MQTT topics and Home Assistant-discoverable entities. Same category of problem, same category of fix, different runtime.
The practical difference reported by the community isn’t in what the mechanism does — it’s in coverage breadth. Zigbee2MQTT’s converter database is generally described as covering more ground on oddball and budget hardware, particularly Tuya white-label devices sold under dozens of rebrands. ZHA’s quirks database, by contrast, is often characterized as covering “thousands” of mainstream devices well, but with a narrower tail on the cheaper, less-branded end of the market.
| ZHA quirk | Zigbee2MQTT converter | |
|---|---|---|
| Where it lives | zha-device-handlers (Python) | zigbee-herdsman-converters (JS/TS) |
| What it fixes | Non-ZCL-compliant device messages, translated for ZHA/zigpy | Same category of fix, translated for Zigbee2MQTT/zigbee-herdsman |
| Portable to the other platform? | No — different language, different internals | No — same reason, reversed |
| Reported coverage strength | Broad on mainstream brands | Broad on budget/Tuya white-label devices |
Why a device can be well-supported on one platform and not the other
This falls directly out of the above: coverage is a function of which contributors wrote which files, not a function of how “supportable” a device inherently is. A device with heavy uptake among Zigbee2MQTT’s more Tuya-focused contributor base can have a mature converter and zero ZHA quirk. A device popular in ZHA’s install base can have the reverse gap. Neither absence means the device can’t be supported — it means nobody has written the file yet for that specific platform.
This is also why “is my device supported” questions don’t have a single yes/no answer independent of platform. The honest answer is always “supported where, and by what version” — checking Zigbee2MQTT’s own device compatibility list is a different lookup from checking whether a ZHA quirk PR has been merged for the same modelID, and the two lists diverge in both directions.
There is no automated translator between a Zigbee2MQTT converter and a ZHA quirk. Porting one to the other is manual re-implementation by someone who understands both codebases — not a conversion tool, not a config flag. Treat any claim of automatic cross-platform support with suspicion.
If a specific device’s Zigbee2MQTT entry is unsupported and you’d rather fix it than switch platforms, our guide on fixing the “no converter available” error covers the practical workflow for writing a converter yourself — including the Tuya TS0601 family, where a converter has to be matched to each device’s specific fingerprint before Zigbee2MQTT will expose it.
The v2-quirks-reference-Z2M-converters convergence (and why it’s not automatic)
The two ecosystems aren’t entirely siloed from each other in practice, even without a translation tool. Newer “v2 quirks” in zha-device-handlers are explicitly designed to make writing a new ZHA quirk easier by using an existing Zigbee2MQTT converter as reference material during development — a pattern the project’s own Tuya v2-quirk guide calls out specifically for Tuya devices, precisely because Zigbee2MQTT’s converter coverage there tends to be ahead of ZHA’s.
That’s a real, if informal, convergence point: someone porting device support to ZHA doesn’t have to start from the ZCL spec and a packet capture — they can read the working Zigbee2MQTT converter for the same modelID and reimplement the same logic in zigpy’s quirk format. It’s still manual work, done by a person who understands both systems, not a build step. The reverse direction (a Zigbee2MQTT contributor using a ZHA quirk as a reference) comes up in maintainer discussions too, without a simpler answer than “read the other implementation and rewrite it here.”
The practical upshot for a reader who isn’t a contributor: if a device sits unsupported on ZHA but has a mature Zigbee2MQTT converter, that gap is more likely to close than a device with no reference implementation on either platform, because the porting work has a concrete starting point. It’s a signal about likely future support, not a guarantee or a timeline.
Practical takeaway — when a specific device should decide your platform choice
For a reader choosing a platform from scratch, general reputation (“Zigbee2MQTT covers more devices”) is directionally true for budget and Tuya-adjacent hardware but isn’t a substitute for checking your specific device. Two checks settle it:
- Look up the exact modelID (not just the marketing name — rebrands are common) on Zigbee2MQTT’s device compatibility list.
- Separately, search or check the zha-device-handlers repository for a merged quirk covering the same modelID.
A device that appears on both lists works either way, and the platform choice can be made on other grounds (MQTT vs. native integration, existing automations, personal preference). A device that appears on only one list makes the platform decision for you, at least for that device — or leaves you with the option covered above: write the missing converter or quirk yourself, treating the other platform’s implementation as your reference, per the v2-quirks pattern above. Individual device guides that walk through building both a converter and a quirk for the same hardware exist already at the device level; this is the conceptual layer that explains why that dual-guide pattern shows up at all.
FAQ
Can I use a Zigbee2MQTT converter file if I’m running ZHA?
No. A converter is JavaScript/TypeScript written against zigbee-herdsman’s internals; ZHA runs on zigpy and Python quirks. Neither platform can load the other’s file directly — the logic has to be manually reimplemented in the target platform’s format.
Why does my device work fine in Zigbee2MQTT but show up as “unsupported” (or with missing entities) in ZHA, or vice versa?
Because the two support databases are maintained independently. A converter existing for a device on one platform says nothing about whether a matching quirk exists on the other — someone has to have written and merged that specific platform’s file.
Are quirks and converters really doing the same thing under the hood?
Yes, at the conceptual level: both translate a manufacturer’s non-ZCL-compliant Zigbee messages into something their respective platform can understand and expose as entities. The implementation languages and internals differ completely.
Can I write a ZHA quirk based on an existing Zigbee2MQTT converter for the same device?
Yes, and it’s an established pattern — newer “v2 quirks” in zha-device-handlers are explicitly designed to be written this way, especially for Tuya devices where Zigbee2MQTT’s converter coverage tends to be more mature. It’s still manual reimplementation, not an automated port.
If I switch from ZHA to Zigbee2MQTT (or back), will a specific device’s features change?
Possibly. Entity names, available attributes, and even whether the device is supported at all can differ between platforms for the same physical hardware, because support is implemented per-platform. Check both databases for your exact modelID before assuming parity.
What this piece actually verifies
This is a documentation-synthesis explainer, not a hands-on test: no coordinator, device, or firmware was paired or bench-tested for it. The mechanism claims — what a quirk does, what a converter does, the v2-quirks-reference-converters pattern, and the absence of an automated porting tool — trace to the zha-device-handlers repository’s own README and its contributor discussions, plus a Home Assistant Community thread describing the conceptual overlap between the two systems. The coverage-breadth claim (Zigbee2MQTT ahead on Tuya/budget hardware, ZHA strong on mainstream brands) is a paraphrase of general community characterization, not a measured count of either database — treat it as directional, not a precise comparison, and check your specific modelID against both projects’ current device lists rather than relying on the general pattern. Everything here stays local either way: neither a quirk nor a converter introduces a cloud dependency, since both operate entirely within your own Zigbee2MQTT or ZHA instance.