Node-RED MQTT Relays: Review the Message Envelope Before Republishing

A Node-RED relay needs an explicit contract for the outgoing message, even when its only visible transformation changes the payload. Incoming MQTT metadata can travel through the flow alongside that payload. Decide which properties describe the original observation and which properties are allowed to control the next publication.

Imagine a hypothetical gateway that receives equipment telemetry, enriches it with a local asset label and republishes it to a reporting broker. The transformation appears correct in a payload-only Debug view. That view does not show whether the destination topic, retention policy or quality-of-service selection still comes from the received message.

Inventory what enters and what leaves

In the pinned Node-RED 5.0.8 MQTT implementation, the receive handler creates a message containing topic, payload, QoS and retain information. MQTT 5 properties can also be copied into the message. The output path applies configured settings and message properties when preparing a publication.

Therefore, review the full message immediately before the MQTT Out node. A payload comparison alone cannot establish the publication contract. Record the intended destination topic, payload representation, QoS, retention choice and any supported MQTT 5 properties. Check their effective values against the installed node version and configuration.

Do not infer that a received retain indication is the desired retention policy for newly derived data. Whether the reporting broker should keep the transformed value is a destination-side design decision. Similarly, the source topic can be useful evidence without being the correct publication destination.

Preserve provenance without leaving control accidental

The official message-design guide treats message properties as an interface. It recommends preserving unrelated properties and explains how a node can overwrite payload while other context still needs to survive. It also identifies topic as a property with meaning to multiple node types.

For the hypothetical relay, preserve approved origin information under a clearly named application property before changing the outgoing topic. Then assign the outbound publication properties deliberately. This creates a visible boundary between the incoming observation and the next-hop policy.

Avoid solving the problem by always replacing the message with a new object containing only payload. That may remove the correlation or routing context required by later nodes. Conversely, forwarding every received property unchanged can preserve settings that were never reviewed for the new destination. The useful design is selective and documented: retain necessary provenance, transform the business data, and set the outgoing control properties intentionally.

Test configuration precedence rather than guessing

Node settings and message values can interact. When a fixed topic is configured on the output node, do not assume that editing the message topic changes the actual destination. When a field is left dynamic, do not assume an upstream value has been cleared merely because it is absent from the last Function node's visible code.

Create a harmless integration fixture with distinctive source and destination topic names. Before publication, inspect the complete outgoing message and the output-node configuration together. Then use an independently configured subscriber to inspect the actual resulting publication. Perform this in an authorized test namespace, not a production command path.

Repeat with the source metadata that matters to the project. Include both retained and live incoming observations if the application consumes both, and exercise the configured protocol version. The purpose is to demonstrate the agreed destination policy, not to assert that all protocol metadata must be copied or discarded.

Keep the relay contract separate from topology

Correct outgoing fields do not prove that a multi-broker topology is loop-free. They also do not prove that the final application accepted the transformed measurement. Those require their own architectural and end-to-end checks. This review answers the narrower integration question: which properties will this flow present to its MQTT output, and why?

The proposed fixtures have not been executed here. A useful handover includes one annotated incoming envelope, the intended outgoing envelope, the relevant output-node settings and the observed publication from the test subscriber. With those artifacts, a later payload change can be reviewed without accidentally changing routing or retention behavior.