Zigbee2MQTT No Converter Available Error: How to Fix It

Pair an unsupported or partially supported Zigbee device and your Zigbee2MQTT log starts filling with a line that looks worse than it is, something like No converter available for 'ClusterName:AttributeName'. It shows up once, then again for a different attribute a few minutes later, and it’s easy to assume the pairing failed.

Most of the time it didn’t. This message is a diagnostic signal, not necessarily an error, and the fix usually doesn’t involve writing any code. There’s also a config change as of Zigbee2MQTT 2.11.0 that broke a lot of older external-converter tutorials without much fanfare. Both are covered below.

One thing to flag up front is that everything here is Zigbee2MQTT-specific. ZHA handles unsupported devices through its own quirks mechanism rather than JavaScript converter files, a different enough approach that it’s not a drop-in substitute for what follows. If you’re still deciding between the two platforms, our ZHA vs Zigbee2MQTT comparison for Aqara devices covers that tradeoff in more depth.

What “No Converter Available” Actually Means

Zigbee2MQTT maps every cluster and attribute a device reports to a named entity through a converter. When a device sends data on a cluster/attribute pair the software hasn’t been told how to interpret, it logs “no converter available” for that specific pair and moves on. It’s flagging a gap, not halting the device.

Multiple GitHub issue threads (#25125 and #24595) describe exactly this pattern. The message recurs one attribute at a time as the device is used, because different clusters get exercised at different moments rather than all at once during pairing. A device can show up correctly in the frontend with several working exposes and still throw this message for a secondary attribute nobody’s built a mapping for yet, like a diagnostic counter or a vendor-specific cluster the main functionality doesn’t depend on.

The distinction that matters is whether the device still exposes the entities you actually need in Home Assistant. If yes, the missing converter is for something cosmetic. If the core functionality (state, battery, the thing the device is actually for) never shows up as an entity, that’s the case worth chasing further.

Before You Write a Converter, Update First

The single most common fix for this error class isn’t a custom converter at all. It’s updating Zigbee2MQTT. Device support lands continuously on the project’s development branch, and a device that throws “no converter available” today can be fully supported two releases later without you doing anything (per a community troubleshooting thread on community.oh-lalabs.com describing this as the standard first move). Check the release notes for your device model before assuming you need to build something.

If updating doesn’t resolve it, the next step still isn’t a blank file. Zigbee2MQTT ships a large library of built-in converter functions (the fz.* namespace) and “modern extend” helpers, small composable pieces that already cover common capabilities like temperature reporting or basic on/off state. Most external converters that people end up writing are a handful of lines wiring together existing helpers, not new parsing logic from scratch. It’s worth a look through the existing helper set before assuming your device needs something novel.

The 2.11+ Wrinkle: External Converters Are Off by Default Now

Here’s the part that trips up anyone following an older guide. As of Zigbee2MQTT 2.11.0, external converters and external extensions are disabled by default on new installations. Even a correctly written, correctly placed converter file won’t load until you explicitly turn the feature back on.

The setting is enable_external_js, and it lives in the advanced section of your configuration.

advanced:
  enable_external_js: true

This isn’t a bug. The Zigbee2MQTT maintainers frame it as a deliberate security tradeoff, because enabling it lets Zigbee2MQTT execute arbitrary JavaScript from whatever file you drop into the converters folder. Worth knowing: that applies to any converter you didn’t write yourself too, so only load ones from a source you actually trust, the same way you’d treat any script you’re about to run with your smart home’s credentials.

The off-by-default flip was a reasonable call even though it quietly broke a lot of existing tutorials that predate it. A feature that runs arbitrary code on your behalf is a sensible thing to gate behind an explicit opt-in, and most users who need external converters are past the point of copy-pasting config blindly anyway.

Step-by-Step: Generating and Extending an External Definition

Zigbee2MQTT can pair with essentially any Zigbee device, supported or not. The workflow for getting an unsupported one working is built into the frontend rather than requiring you to reverse-engineer clusters by hand.

1. Pair the device normally. It’ll show up in the device list even without a converter.
2. Open the device’s Exposes tab and see what’s already been auto-discovered. Sometimes more than you’d expect works out of the box through generic cluster handling.
3. In the Dev Console tab, use the “Generate external definition” option. This produces a starting-point converter file based on what Zigbee2MQTT can already see about the device’s clusters.
4. Extend that generated definition with the specific entities you need, then save it.

Converter files live in an external_converters folder that sits at the same filesystem level as configuration.yaml.

zigbee2mqtt-data/
  configuration.yaml
  external_converters/
    my-device.js

Whether a new or edited converter takes effect immediately depends on how you load it. A .js file you place or edit directly in the external_converters folder is read at startup, so a change made on disk needs a Zigbee2MQTT restart to be picked up. There’s also a runtime path that skips the restart: saving through the frontend (Settings > Dev console > External converters), or the equivalent zigbee2mqtt/bridge/request/converter/save MQTT request, applies the converter immediately without restarting. Zigbee2MQTT republishes its zigbee2mqtt/bridge/converters list whenever a converter changes that way. A restart, for what it’s worth, doesn’t un-pair anything, your devices stay joined and the network is preserved, but it does make them briefly unavailable while the process comes back up, which the runtime path avoids.

Common Failure Modes When External Converters Don’t Load

Two things account for most “I added the converter and nothing changed” reports.

• enable_external_js isn’t set. As of 2.11.0 this is the default state on any fresh install, and the failure is silent. No error banner, the converter just doesn’t apply.
• The folder is in the wrong place. The external_converters directory needs to sit next to configuration.yaml, not inside it or in some other data directory, especially on Docker or Supervisor setups where multiple paths can look plausible.

GitHub issue #26199 is one of several reports describing converters that stopped loading after an update. The thread itself doesn’t call out enable_external_js specifically, but it’s the first thing worth checking against any “this used to work” report on a recently updated instance, since that’s the most common cause since 2.11.0 shipped.

This is the same shape of problem that shows up elsewhere in Home Assistant: a routine update quietly changing behavior that an older guide doesn’t account for. The Home Assistant 2026.7 release did something similar with a trigger and condition rename that silently broke ZHA automations built against the old keys, another case where the fix is knowing what changed, not rewriting your setup from scratch.

FAQ

What does “No converter available” mean in Zigbee2MQTT?
It means the software received data on a cluster/attribute pair it doesn’t have a mapping for yet. It’s a per-attribute diagnostic message, not a signal that the device or the pairing failed outright.

Why did my external converter stop working after updating Zigbee2MQTT?
Almost certainly the 2.11.0 change that disabled external converters and extensions by default on new installations. Check enable_external_js in your advanced config before troubleshooting anything else.

Do I need to restart Zigbee2MQTT after adding an external converter?
It depends on how you add it. A converter file you place or edit directly in the external_converters folder is read at startup, so it needs a restart to take effect. If you instead save it through the frontend’s Dev console (Settings > Dev console > External converters) or the zigbee2mqtt/bridge/request/converter/save MQTT request, it’s applied at runtime with no restart.

Is enable_external_js safe to turn on?
It’s safe in the sense that it’s an intentional, documented feature. The tradeoff is that it lets any file in your converters folder execute arbitrary JavaScript, so the real safety question is whether you trust the specific converter you’re loading, not whether the setting itself is risky.

Can I load an external converter without a full restart?
Yes. Save it through the frontend’s Dev console (Settings > Dev console > External converters) or the zigbee2mqtt/bridge/request/converter/save MQTT request, and it’s applied at runtime. Only converters added or edited directly as files on disk require a restart.

Zigbee2MQTT’s own device-support library keeps growing, which is exactly why updating resolves more of these than any converter tutorial does. Whether the frontend’s converter generator eventually gets folded into an automatic pull-request flow for common device patterns is worth watching. For now it’s still a manual step, and one that needs the enable_external_js flag flipped before it’s worth doing at all.