Install & Compatibility
Where this runs
tested against v? · npm install
Install × environment matrix
Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux
muslnode 18–226 runs
build_error
glibcnode 18–226 runs
build_error
Code
Verified usage
Verified import paths — ran on the pinned version, not inferred.
Node-RED Editor Palette
✓ N/A
This package is a Node-RED contribution; it makes new nodes available in the Node-RED editor's palette after installation. Users interact with the 'Aedes MQTT Broker' node graphically within the editor, rather than through direct JavaScript/TypeScript imports.
Installation Command (NPM)
✓ npm install node-red-contrib-aedes
✗ N/A
The primary method to make the Aedes broker node available in your Node-RED instance is via the Node-RED Palette Manager GUI or by executing this command in your Node-RED user directory.
Node Configuration
✓ N/A
Once installed and added to a flow, the Aedes MQTT Broker node's settings (e.g., ports, SSL, and persistence) are entirely configured through its properties panel in the Node-RED graphical editor.
Installs the Aedes MQTT broker node into your Node-RED environment, making it available in the palette for graphical configuration and deployment within your Node-RED flows.
// Step 1: Install the Node-RED contribution package
// This command should be run in your Node-RED user directory (e.g., ~/.node-red)
// or via the Node-RED Palette Manager GUI.
// Execute in your terminal:
// npm install node-red-contrib-aedes
// Step 2: Restart Node-RED
// After successful installation, restart your Node-RED instance.
// For example, by running 'node-red' in your terminal or restarting its service.
// Step 3: Access and Configure in Node-RED Editor
// - Open your Node-RED editor (typically at http://localhost:1880).
// - Find the 'Aedes MQTT Broker' node in the MQTT category of the palette.
// - Drag this node onto your flow canvas.
// - Double-click the node to open its configuration panel.
// - Configure desired settings, such as TCP port (e.g., 1883), WebSocket port (e.g., 8080),
// SSL/TLS settings, and message persistence options.
// - Deploy your flow to start the embedded MQTT broker.
console.log("Aedes MQTT Broker node installed and ready for configuration in Node-RED editor.");
// For testing, connect any MQTT client to the configured broker (e.g., mqtt://localhost:1883).
Debug
Known issues
breakingVersions 1.0.0 and above of `node-red-contrib-aedes` are based on Aedes version 1.0, which introduced significant breaking changes compared to previous Aedes versions (0.x).fixReview the Aedes v1.0 migration guides for any necessary adjustments to your MQTT client configurations. If strict compatibility with Aedes 0.51 is required, install `node-red-contrib-aedes@version-15`.
affects: >=1.0.0
breakingVersions `>=1.0.0` (and `0.15.x`) of this package require Node.js version 20 or newer, and Node-RED version 3.0 or newer. Running on older environments will lead to runtime errors or installation failures.fixUpgrade your Node.js and Node-RED installations to meet the minimum requirements. For environments constrained to older Node.js versions (e.g., less than v20), install `node-red-contrib-aedes@version-11`.
affects: >=1.0.0, >=0.15.0 <1.0.0
gotchaThis package replaces older Node-RED MQTT broker nodes (e.g., `node-red-contrib-mqtt-broker`) that relied on the unmaintained Mosca library. While functionally similar, Aedes may have behavioral differences in specific MQTT protocol implementations or configuration options.fixWhen migrating from Mosca-based brokers, thoroughly test existing MQTT client configurations and review Aedes documentation for any subtle behavioral changes or new features.
affects: all
gotchaEnsuring proper port availability and firewall configuration is crucial for external clients to connect to the embedded Aedes broker, especially for TCP and WebSocket listeners. If deployed behind a reverse proxy, WebSocket paths need careful setup.fixVerify that configured MQTT ports (e.g., 1883, 8883, WebSocket ports) are open on your server's firewall. For WebSocket connections via a reverse proxy, ensure the proxy correctly forwards WebSocket traffic to the Node-RED instance at the specified path.
affects: all
Errors
Common errors & fixes
Error: The module 'aedes-persistence-mongodb' was compiled against a different Node.js version
Node.js version mismatch between the environment where the package was installed and where it's being run, or an incompatible version of Aedes or its persistence plugins.
fixEnsure your Node.js version meets the package requirements (>=20 for v1.x). Remove `node_modules` and reinstall `node-red-contrib-aedes` to recompile native modules against the current Node.js version.
Error: Node-RED version not supported. Minimum required is 3.0.0
Attempting to run `node-red-contrib-aedes` version 1.x or 0.15.x on an older Node-RED instance.
fixUpgrade your Node-RED installation to version 3.0 or higher. If upgrading is not possible, use `node-red-contrib-aedes@version-11` for older Node-RED environments.
MQTT Client Connection Refused / Connection Timeout
The Aedes broker node is not running, its configured ports are blocked by a firewall, or the client is attempting to connect to an incorrect address or port.
fixVerify the Node-RED flow containing the Aedes broker node is deployed and running (check Node-RED logs for errors). Ensure the configured MQTT ports are open on the host machine and that client connection details (IP, port, protocol) are correct.
Audit
Dependencies
aedesrequiredCore MQTT broker implementation library.
node-redrequiredRuntime environment for this contribution package.