MQTT node, bundled package, added package, optional extension — keep these apart

The urge with MQTT is to open the mqtt out node, type a topic, and move on. Before you do, it is worth knowing which of four different layers you are actually touching, because they carry completely different amounts of risk. The Node-RED Home Assistant add-on this guide follows is version 22.0.1, and it embeds Node-RED 5.0.2 and the HA WebSocket integration at 0.80.3.

The add-on also carries two grants worth knowing about before you go further: host_network: true and uart: true, plus media:rw and share:rw storage access. None of these mean MQTT, a serial node, or a file node is actually in use — they mean the container can reach further than a sandboxed add-on normally would, if a flow inside it asks to. Treat every grant as a ceiling on what is possible, not a report on what is happening.

flowchart TD
  A["Node-RED core
mqtt in, mqtt out, mqtt-broker"] --> B["Ships inside Node-RED 5.0.2 itself.
Nothing to install, nothing to audit"]
  C["The add-on's 25 bundled dependencies
pinned in package.json"] --> D["Already present the moment
the add-on starts. You chose none of them"]
  E["Palette Manager, or npm_packages
in the add-on's own options"] --> F["Third-party code you add on purpose.
Runs with the same permissions
as Node-RED itself"]
  G["FlowFuse Dashboard 2
@flowfuse/node-red-dashboard"] --> H["Optional. Not one of the 25.
You have to add it yourself, and secure it yourself"]

Ticking a box rarely does everything you assume it does

Every MQTT setting on a Node-RED node answers one narrow question. The broker connection settles the transport, the protocol version, and the session. MQTT In settles the subscription filter, the subscription QoS, and the shape of the data coming out. MQTT Out settles the publish topic, its QoS, its Retain setting, and any MQTT 5 properties riding along. Ticking the TLS checkbox does not create a topic ACL. Choosing QoS 2 does not make whatever happens downstream in your flow run “exactly once.” The table below is the seven ideas worth knowing apart, with the misreading that trips people up sitting right next to the real meaning.

Protocol version matters more than it looks. MQTT 5 adds properties and subscription flags that simply do not exist under 3.1 or 3.1.1: a Response Topic, correlation data, content type, message expiry, user properties, No Local, Retain As Published, Retain Handling, and session expiry. Pick MQTT 3.1 or 3.1.1 and none of that is available to you — not because Node-RED hid it, but because the protocol version you chose does not carry it. Pin the version your broker actually supports before you configure a node around it; do not let a client guess.

Six checks you can finish without a broker in sight

Everything in this section happens on paper, or in a text file — not against a running broker. The first four checks apply to anyone touching MQTT at all. The last two only apply if you are also auditing packages or planning a Dashboard change; skip them if MQTT is all you came for.

1. Step 1

   Write a topic contract

   For each direction data flows, write down a placeholder topic, the publisher, the subscriber, the payload's shape, its maximum byte size, how often it is allowed to fire, its QoS, its Retain setting, and how duplicates are handled. Do not put a real broker address, a real client ID, or real credentials into this document.

2. Step 2

   Decide the protocol and the session behavior

   Write down MQTT 3.1, 3.1.1, or 5 explicitly. Then decide clean session or clean start, the client ID, automatic unsubscription, and — only under MQTT 5 — session expiry. Leave blank whatever the protocol version you chose does not support.

3. Step 3

   Read the example flow, offline

   Open 14-mqtt-in-out.json without importing it live. Confirm both the MQTT In and MQTT Out nodes carry d:true, that the broker configuration has autoConnect:false, and that the host, client ID, and topics are all complete placeholders with no credentials anywhere in the file.

4. Step 4

   Check TLS and ACLs on paper

   In your written specification, require a controlled TLS configuration, server certificate verification, separate credentials per client, and least-privilege publish/subscribe ACLs per topic. Never write a secret into a broker URL, a Function node, an exported flow, or Debug output.

5. Step 5 — conditional

   Inventory where every package came from

   Only if you are auditing the bundled nodes or evaluating a new install: compare against the 25-entry matrix later in this part. Record the exact npm package and pinned version, its maintenance status, its license, its transitive dependencies, its permissions, and how you would remove it. MQTT-only readers can skip this step entirely.

6. Step 6 — conditional

   Write down failure and recovery, for packages or Dashboard work

   Only if packages or FlowFuse Dashboard are involved: document what a package startup failure looks like, what a routing or Socket.IO problem looks like, and how you would recover. In the MQTT topic contract, also record what broker unreachability, a certificate error, an ACL denial, a duplicate, a stale retained message, or a session recovery would look like. Keep the relevant nodes disabled and do no I/O while you write this.

The literal contract from the source material looks like this — a template to fill in, not a live configuration:

The check you run before calling this part done

The exact fields on Node-RED 5.0.2's two MQTT nodes

MQTT In has five things you decide: which broker, what topic or action, what QoS, which MQTT 5 flags, and what shape the output takes.

What comes out of MQTT In always includes msg.topic, msg.payload, msg.qos, and msg.retain. An MQTT 5 packet can also carry responseTopic, correlationData, contentType, messageExpiryInterval, payloadFormatIndicator, reasonString, and userProperties.

MQTT Out: whichever value is set on the node wins

MQTT Out has Broker, Topic, QoS, and Retain fields. If Topic is left blank on the node, it falls back to msg.topic. If QoS or Retain is left blank, they fall back to msg.qos or msg.retain. But a value fixed directly on the node always takes precedence over the same value carried on the message — and that flexibility cuts both ways: an untrusted message can change what gets published if you leave the node's fields empty.

flowchart TD
  A["A message reaches MQTT Out"] --> B{"Is Topic filled in
on the node itself?"}
  B -->|"yes"| C["The node's Topic wins.
msg.topic is ignored"]
  B -->|"no"| D["msg.topic is used instead"]
  A --> E{"Are QoS or Retain set
on the node itself?"}
  E -->|"yes"| F["The node's values win.
msg.qos / msg.retain ignored"]
  E -->|"no"| G["msg.qos or msg.retain
is used instead"]

MQTT 5 also lets MQTT Out carry User Properties, a Response Topic, Correlation Data, Content Type, and Message Expiry. A Response Topic is protocol metadata, nothing more — it does not, by itself, create a secure request/response mechanism. If you want a reply pattern out of it, the ACL on the reply topic, the uniqueness of the correlation ID, a timeout, duplicate handling, and what happens to a late reply are all design decisions you still have to make yourself. And whichever node you are setting it on: a publish topic can never contain the + or # wildcards, even though a subscription topic can use either freely.

flowchart TD
  A["A topic string you are
about to type"] --> B{"Does it contain
a + or a # ?"}
  B -->|"no"| C["Fine either way.
home/kitchen/temp works on
MQTT In or MQTT Out"]
  B -->|"yes"| D{"Which node are
you setting it on?"}
  D -->|"MQTT In (subscribe)"| E["Accepted. home/+/temp or
home/# are valid filters"]
  D -->|"MQTT Out (publish)"| F["Rejected. A publish
topic names one exact topic"]

Connection, session, security, messages, and the MQTT 5 extras — five separate groups

The mqtt-broker configuration node is where the transport, the protocol version, and the session actually get decided. Node-RED 5.0.2 groups its settings into five parts.

Protocol Version is a plain number on the node: 3 means MQTT 3.1 compatibility, 4 means MQTT 3.1.1, and 5 means MQTT 5. If a node you imported from an older flow still reads 3 or 4 and you need the MQTT 5 properties from the previous section, that number is the first thing to change — and the first thing to confirm your broker actually supports.

When Auto-connect is turned off, Node-RED 5.0.2 still allows a controlled action message to connect or disconnect the broker on command. That capability is not meant as an entry point for outside traffic: never wire an external payload from MQTT In or HTTP In straight into broker control. And because the add-on's host_network: true grant can put more of your local network within reach of the container, a broker allowlist and real ACLs matter more here than they would in a fully sandboxed setup.

The 25 pinned dependencies, and what running any of them actually means

The add-on's node-red/package.json pins exactly 25 direct dependencies: 19 give you Palette or configuration nodes, 1 is the Node-RED runtime itself, 1 is an editor theme, and 4 are wrapper or runtime support libraries that never show up as a node you can drag onto a canvas. Preinstalled means available — it does not mean any flow has actually run the package. If MQTT is all you came for, you can skip straight past this table to the next section.

Read that table by function, not just by name. node-red-contrib-cast, node-red-contrib-influxdb, node-red-contrib-modbus, node-red-node-email, node-red-node-feedparser, node-red-node-ping, and node-red-node-serialport can all perform network, database, or physical I/O. node-red-contrib-bigtimer, node-red-contrib-sunevents, and node-red-node-suncalc can generate messages on their own, based on time, with nobody clicking anything. And even the ones that look like pure transformation — node-red-contrib-counter, node-red-contrib-moment, node-red-node-smooth — can hand a wrong result to whatever acts on it downstream. Being bundled is not a reason to skip validating any of them.

On every startup, the add-on installs system_packages with the Alpine package manager first, then changes into /opt and runs npm install --omit=dev --omit=optional for anything listed in npm_packages, then finally runs eval on each line of init_commands. Any single failure in that chain aborts the whole startup.

flowchart LR
  A["system_packages
installed with the Alpine
package manager"] --> B["npm_packages
cd /opt, then
npm install --omit=dev --omit=optional"]
  B --> C["init_commands
each line run with eval"]
  C --> D["Node-RED starts"]
  A -.->|"fails"| X["Startup aborts"]
  B -.->|"fails"| X
  C -.->|"fails"| X

Do not record just a package name with a loose version range. At minimum keep the exact version, the registry identity, the source repository, the license, the maintainer, the publish date, any known advisories, Node and Node-RED compatibility, a summary of the transitive tree, and a rollback version. Pinning your direct dependency does not freeze every transitive one underneath it. And because the add-on's backups explicitly exclude node_modules, a restore does not reproduce the installed tree byte for byte — your own notes, plus an available registry, are what let you rebuild the same dependencies afterward. Do not manage the same package through both Palette Manager and npm_packages at once; that is how ownership and version both go ambiguous.

File nodes and the storage grants

Node-RED's core also ships File, File In, and Watch. The add-on's media:rw and share:rw grants give the container potential read/write reach — they do not, on their own, authorize any flow to touch any particular path. If a file name is ever built from MQTT, Dashboard, or HTTP input, that opens the door to path traversal, overwriting, or exfiltration. Pin the base directory, allowlist the file names you accept, cap the byte size and the frequency, and keep every write disabled until you have reviewed it. The same logic applies to serial nodes: uart: true is a grant, not approval to run an arbitrary device command.

Twenty-seven registrations, and a boundary you have to draw yourself

The 25-entry list in the previous section does not include @flowfuse/node-red-dashboard. The pinned version, 1.30.2, declares it needs Node >=14 and Node-RED >=3.0.0. Node-RED 5.0.2 sits inside both of those ranges, but that is a declared compatibility range, not a guarantee — you still test it against this specific add-on before relying on it. Installing it registers 5 configuration nodes and 22 ui-* widgets, 27 registrations in total, and it brings its own server code, its own browser code, an HTTP route, and a Socket.IO channel along with it.

The add-on's direct /endpoint/ NGINX path does not pass through the editor's Supervisor auth_request. Ingress only accepts the Supervisor's own ingress source, and that on its own does not prove every Dashboard viewer has authorization for every widget. Check directly whether http_node Basic Auth is actually protecting your route, and the Socket.IO session, over the real proxy path you use — not just the editor. With a custom Dashboard path, test that custom route and the hard-coded /dashboard/manifest.webmanifest separately, because a login requirement on the editor does not automatically extend to the Dashboard page, its manifest, its assets, or its real-time channel.

If you already run the legacy Dashboard

The old, unscoped node-red-dashboard is built on Angular v1 and is considered legacy; nothing here teaches a fresh install of it. Its interim scoped name, @flowforge/node-red-dashboard, is deprecated and no longer updated. FlowFuse Dashboard 2 is a rewrite, not a drop-in replacement — do not assume existing ui_* nodes, themes, layouts, custom templates, browser scripts, URLs, authentication, or client state carry over automatically.

Inventory the existing flow's pages, groups, widgets, template code, routes, authentication, CSS, browser dependencies, and message contracts first. Rebuild it page by page in an isolated copy, and compare the two side by side. If you run the legacy and new Dashboards at the same time during migration, you also have to prevent conflicts in routes, Socket.IO, credentials, and duplicated side effects. Do not remove the old package first, and do not point a new widget at a production action until the comparison is finished.

The failures that actually happen here

The ones that come up again and again

Where to go from here