I’m trying to implement an external converter file, rdm005.mjs, into my system but I’m finding conflicting information from searches on how to configure the zigbee2mqtt configuration.yaml file and where the external_converters directory needs to be. So far everything I try is not yielding zigbee2mqtt log statements indicating that the converter is loaded.
Should there be a reference to the converter file in the configuration.yaml and where in the hierarchy should it be placed?
Where should the converter file be saved? /homeassistant/zigbee2mqtt/data/external_converters, or perhaps, /homeassistant/zigbee2mqtt/external_converters
Is it okay to make all these changes with the HA File Editor or should the CLI be used. Also, do you need to be setting file permissions and ownership with the CLI?
Not really. As long as you create the folder in the right place (see below), Z2M will pick up the converters automagically.
If you’re using File Editor, it should be homeassistant/zigbee2mqtt/external_converters. If you’re using Samba share, it’ll be HOMEASSISTANT\config\zigbee2mqtt\external_converters
File Editor is fine. Notepad++ (if you’re using Samba Share) or VSCode addon works too.
Any results from before the end of 2024 will be stale because there was a huge overhaul once Z2M 2.0 was launched around the beginning of 2025. The 2.0 update changed the default location of the external converters and also coincided with the more modern extends, hence the discrepancy in your search results.
I suggest you always refer to the official docs, however technical they might seem.
This is showing a directory called “data” which if not true is misleading.
The Docs also have this, which I have yet to see in my log:
When Zigbee2MQTT starts it publishes zigbee2mqtt/bridge/converters with payload [{“name”: “my-first-converter.js”: “code”: }] containing all the converters loaded from the file system.
Another question is if the file is incorrect in some way will the log file indicate an error or just be silent?
/data is mapped to your zigbee2mqtt folder, wherever it is. Remember that Z2M is used in loads of applications outside of HA, and can even be run standalone. Read this comment for context.
Assuming your file path is correct, then you should see something even if the file is incorrect.
I just tested this out for you by creating the folder and adding an old format(.js) external converter. This is what I see in the log:
[2025-07-22 20:08:28] error: z2m: Invalid external converter 'QBKG32LM.js' was ignored and renamed to prevent interference with Zigbee2MQTT.
I’m not sure why creating the external_converters directory and then creating the file in that folder wasn’t working. Grok seems to think it is all about folder/file ownership and permissions. He had me in the CLI running BASH commands but we were never successful until online save.