private@homelab: ~/latest
Home Assistant · Zigbee2MQTT · local control
lightdark
private@homelab:~$ cat guides/article.md
·
·
4–6 minutes
read

Zigbee2MQTT No Converter Available Error: How to Fix It

Zigbee2MQTT logging 'No converter available' on repeat? Here's what the message means, when to ignore it, and the 2.11+ config change that broke old fixes.

Person editing a Zigbee2MQTT external converter in the development console for a device with no converter available

Zigbee2MQTT No Converter Available Error: How to Fix It

A line such as No converter available for 'ClusterName:AttributeName' means Zigbee2MQTT received a report it could not interpret. The device may still be paired and working for its supported features.

Check what is missing before changing anything. An unused diagnostic report may need no action; a missing switch state or sensor reading does. External converters are one option, and new installations from Zigbee2MQTT 2.11.0 onward require them to be enabled explicitly.

These steps apply to Zigbee2MQTT. ZHA uses device handlers called quirks, so its troubleshooting steps differ. Our ZHA vs Zigbee2MQTT comparison for Aqara devices explains the two approaches.

What “No Converter Available” Actually Means

Converters interpret supported Zigbee reports and expose values or controls. An unmapped cluster or report can produce this log message without stopping the rest of the device’s functionality.

A device can expose its main controls while logging unmapped reports from a secondary or manufacturer-specific cluster. Read the cluster name alongside the feature that is failing; repeated log entries alone do not show that pairing failed.

Test the features you need in Home Assistant. If they work, investigate the unmapped report before deciding it can be ignored. If a required state or control is missing, check device support, the interview result, and the converter load logs.

Before You Write a Converter, Update First

Check your installed version and the device’s support page first. A newer stable release may already include the needed converter. Back up the Zigbee2MQTT data directory and read the release notes before updating.

For an unsupported device, inspect existing converters and modernExtend helpers before writing a parser. Standard temperature, battery, or on/off reports may already have reusable handling. Manufacturer-specific data points can need additional work.

Enable external converters on new 2.11+ installations

The external converter documentation says that external converters and extensions are disabled by default on new installations from version 2.11.0. Check the setting on your own installation; an upgrade is not evidence that this option caused the failure.

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

advanced:
  enable_external_js: true

External converters execute JavaScript inside Zigbee2MQTT. Review the source before enabling one, especially if it comes from a forum attachment. The setting permits execution; it does not make an unknown converter trustworthy.

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

An unsupported device may join the network even though its reports are not understood. The frontend can generate a starting definition from the interview, but manufacturer-specific data may still need manual work.

  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.mjs

Changes made directly to files in external_converters need a restart. Saving through Settings > Dev console > External converters, or the MQTT bridge/request/converter/save request, applies the change at runtime. Check zigbee2mqtt/bridge/converters to confirm what loaded. Restarting the service briefly interrupts the bridge but does not unpair the devices.

Common Failure Modes When External Converters Don’t Load

Start with these checks, then read the startup log for converter errors:

  • enable_external_js isn’t set. On new installations from 2.11.0 onward, external JavaScript needs explicit enablement. Check configuration and startup logs before assuming the file was loaded.
  • 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.

If a converter stopped loading after an update, read the startup log for import or API errors as well as checking enable_external_js. A converter written for an older library version may need changes even when the setting is enabled.

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 an update? Check the enablement setting, file location, and startup errors. Imports or converter APIs may have changed. The disabled-by-default setting applies to new installations, so it should not be assumed to explain every upgrade problem.

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 is a documented feature that permits external JavaScript to run. Enable it only for converter code you have reviewed and trust.

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.

Once a converter works, consider submitting it to the project. After built-in support reaches your installed release, remove the external copy so you do not keep overriding the maintained definition.

local-firstHome Assistantno-cloud