Skip to main content
WebsiteGitHub last commitGitHub commit activityGitHub IssuesDocker PullsDiscordLocalized

Writing Functions

The function node runs JavaScript against each message that arrives. Use it when the built-in core nodes can't express your logic cleanly: several conditions, math with several values, remembered state, or building a complex message.

This page covers the basics. The rest of the section builds on it:

The code is the body of a function​

What you type in the On Message tab is the body of a function. Node-RED calls it once for each message, and the message is available as msg. The simplest function returns the message unchanged:

return msg;

Here is one that changes the payload:

msg.payload = msg.payload * 2;
return msg;

What you can return​

You returnWhat happens
msg (an object)The message is sent to the output.
null or nothingNo message is sent, and the flow stops here.
An arrayThe messages go to different outputs. See outputs and messages.
A number, string, or booleanAn error. A function must return a message object.

Returning null is how you filter. This passes only payloads above 75:

if (msg.payload > 75) {
return msg;
}
return null;

Reuse the incoming message​

You can build a brand new message instead of reusing msg:

return { payload: msg.payload.length };

That works, but the new message loses every other property of the old one, including msg.topic, msg.data, and anything an earlier node added. Some nodes depend on those properties being passed along. As a habit, change the message you were given and return it, and only start from scratch when you mean to.

The editor dialog​

Double-click a function node to open it. It has several tabs:

TabRunsUse it for
SetupNever. It holds settings.The node's Name, the number of Outputs, the Timeout, and the list of extra Modules.
On StartOnce, when the node starts after a deploy or restart.Setting up values, such as default context. Messages that arrive while it runs wait until it finishes.
On MessageFor every incoming message.Your main logic.
On StopWhen the node stops, because of a deploy or shutdown.Closing connections or other tidying up.

The Timeout is in seconds, where 0 means no limit, and it only applies to synchronous code. Older versions of Node-RED call the On Start tab Setup and keep the settings on the first tab.

Use the full-screen editor

Click the expand icon at the bottom right of the code box for a bigger editor with syntax highlighting. It flags many typing mistakes before you deploy.

What you can use inside a function​

These objects are always available:

ObjectWhat it is
msgThe incoming message.
nodeThe function node itself, for logging, status, and sending messages.
context, flow, globalStorage for values you want to keep. See context and timers.
envEnvironment variables. env.get("TZ") reads one.
RED.util.cloneMessage(msg)Makes a safe copy of a message.
setTimeout, clearTimeout, setInterval, clearIntervalJavaScript timers.
Buffer, util, consoleStandard Node.js helpers. Prefer node.log over console.

Modern JavaScript works, including const, let, arrow functions, template strings, destructuring, and optional chaining (?.). What is available depends on the Node.js version Node-RED runs on.

Log what is happening​

Use these to see what your code is doing:

node.log("Something happened");
node.warn("Something happened that you should know about");
node.error("Something went wrong");

node.warn and node.error show up in the Debug sidebar, which makes node.warn the easiest way to look at a value while you build:

node.warn("payload is " + JSON.stringify(msg.payload));

node.log goes to the Node-RED log, which is the console you started it from, or the add-on or container log. There are also node.debug and node.trace for finer-grained logging, but they only appear if the log level is set to show them.

Remove the noise when you're done

A node.warn that runs on every message will flood the Debug sidebar and your log. Remove it once the function works, or wrap it so it only runs when something is wrong.

Show a status under the node​

A function node can show its own status text and color under the node, like other nodes do:

node.status({ fill: "green", shape: "dot", text: "Home" });
node.status({ fill: "red", shape: "ring", text: "Not home" });
node.status({ text: "Just some text" });
node.status({}); // clears the status

Colors are red, green, yellow, blue, and grey, and shapes are dot and ring. A status is a quick way to see what a function last decided without opening the Debug sidebar. It only changes when you call node.status, so it can show an old result until the next message.

Handle errors​

Two things can go wrong: your code throws an error, or you detect a problem yourself.

If code throws an error, for example by reading a property of undefined, Node-RED logs the error and stops handling that message. A catch node on the same tab receives it.

To report a problem yourself and make a catch node react, call node.error with the original message as the second argument, then return nothing:

if (typeof msg.payload !== "number") {
node.error("Expected a number but got " + typeof msg.payload, msg);
return null;
}
return msg;

Check before you read​

The most common error is Cannot read properties of undefined. It happens when you read a property of something that isn't there. Optional chaining (?.) and a default value (??) avoid it:

// Throws if msg.data or new_state is missing:
const state = msg.data.new_state.state;

// Safe. Gives undefined if anything along the way is missing:
const safeState = msg.data?.new_state?.state;

// Safe, with a default:
const stateOrDefault = msg.data?.new_state?.state ?? "unknown";

Test a function​

The quickest way to test is to wire an inject node into the function and a debug node after it. Set the inject node to send the kind of payload you expect, such as a JSON object, click it, and read the result in the Debug sidebar. Test the odd cases too: a missing property, an empty string, and the wrong type.

A handy trick is to use node.warn at the top of the function to show the whole incoming message:

node.warn(msg);

Click the message in the Debug sidebar to expand every property.

Common mistakes​

MistakeWhat you'll seeFix
Forgetting return msgNothing comes out.Return the message.
Returning a string or numberAn error saying the function must return an object.Put the value in msg.payload and return msg.
Building a new message and losing propertiesA later node can't find msg.topic or similar.Change and return msg instead.
Using return inside a callback or timerNothing is sent.Use node.send(). See outputs and messages.
Comparing a string to a number"5" === 5 is false.Convert with Number() or String().
Reading a property that may not existCannot read properties of undefined.Use ?. and ??.
Buy me a beer


💬 Discord Community Chat

Join the conversation! Comments here sync with our Discord community.

💬 Recent Comments

Loading comments...