Diagnose Missing msg.payload in Node-RED Flows

When a Node-RED flow shows no output despite expected input, the payload may be undefined. Follow this diagnostic guide to locate and resolve the issue.

Recognizable condition

When a Node‑RED flow appears to do nothing – no debug output, no UI change – even though an upstream node should emit data, the root cause is often an undefined msg.payload.

Cause / Diagnostic table

\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n

#	Possible cause
1	No input node or wrong node type; the flow never receives a message.
2	A `change` node explicitly clears `msg.payload` or sets it to `null`.
3	A `function` node returns without assigning `msg.payload`, leaving it undefined.
4	Flow context variables are missing or mistyped, causing downstream nodes to receive no data.
5	The flow file has unsaved changes; the editor shows an asterisk but the runtime still uses the old version.

Ordered checks

Confirm the upstream node’s output type. Check the node’s output label in the palette. If it shows “Object”, “String”, “Number”, etc., the payload will be that type. If the node outputs “null” or “undefined”, the next node will receive no payload.
Add a temporary function node right after the suspected node and log msg.payload with node.log(JSON.stringify(msg.payload)). Deploy and open the debug sidebar; the JSON string will reveal whether a payload exists and its content.
Inspect every change node in the path. Look for statements such as msg.payload = null or return {} that drop the payload. Replace them with return {payload: msg.payload} if you need to keep the original value.
Check that the flow is saved (no asterisk) and then redeploy. Unsaved edits are not sent to the runtime.
Verify flow context usage. If a downstream node reads flow.get('myVar'), add a function node that logs flow.get('myVar') to confirm the key exists and holds a non‑empty value.

Fixes tied to findings

Make sure the upstream node actually sends a payload. For testing, connect an inject node set to payload: \"test\" and verify it reaches the next node.
If a change node clears the payload, modify it to return {payload: msg.payload} or remove the clearing line.
In function nodes, always end with return {payload: some value} or return msg; to preserve the original message.
Use flow.set('key', value) and flow.get('key') for persistent data when a node does not provide a direct payload.
After any edit, click the red Deploy button and watch for the “Flow deployed” message in the sidebar.

Concrete example

// Example function node that forgets to set payload\nfunction process(msg) {\n    // do some calculation, but never assign msg.payload\n    node.log(\"calculation done\");\n    // missing: return {payload: msg.payload};\n    return msg; // payload remains whatever it was, possibly undefined\n}\n

If the input message has payload: \"hello\", the output will be undefined because the node never sets it.

Escalation criteria

When all ordered checks pass and the debug output still shows undefined or no output, consider the following escalation steps:

Upgrade Node‑RED to the latest stable release (currently 4.x). Older 3.x versions may have bugs in payload handling for certain message types.
Re‑import the flow from version control or from a backup to rule out corruption of the flow file.
Open an issue on the Node‑RED forum, providing the flow JSON and a description of the missing payload.

Verification steps

Run the flow, inject a test message with a known payload (e.g., {\"payload\":\"test-value\"}), and confirm the downstream debug node displays that exact value.
After each change, reload the flow editor, redeploy, and re‑inject the test message to ensure the payload is now present.
Watch the Node‑RED console for warnings such as “msg.payload is undefined” that may indicate a deeper bug.

Cautions

Version compatibility: Node‑RED 3.x and earlier may mishandle binary buffers or custom message types; verify you are on a version that supports the payload you use.

Backup: Before making extensive edits, copy the .json flow file to a safe location; you can restore it if a change breaks the flow.

Security: Avoid exposing sensitive data in msg.payload when using HTTP nodes; sanitize or mask the value before transmission.

Node-RED Silent Data Drop: Diagnose and Fix Missing msg.payload