Making a flow reusable and knowing whether it worked are not the same skill

Once the same logic has been copied across three tabs, a fix will usually reach only two of them. Node-RED gives you five different tools for the reuse problem — Link nodes, Subflows, the Library, import/export, and Projects — and each one solves a different slice of it. Treat them as one big “reuse” bucket and you end up trusting a Link Out that was never going to return, or handing someone an export that still carries your real broker address inside a Comment nobody read.

The second half of this part is a separate mistake, and a more common one. Four Node-RED nodes exist to tell you what actually happened — Debug, Catch, Status, and Complete — and each of them answers a narrower question than it looks like it does.

A one-way wire, and the one Link Out that closes a loop

Link In and a Link Out in its normal, “send to all” mode create virtual wiring between flow tabs. When a Link Out receives a message it forwards it to every connected Link In. That is message delivery, not a call with a return value. Because the wiring is virtual rather than a drawn wire, it is usually visible only when you select the Link node — which is exactly why each one needs a name that identifies both the action and the contract, something like “Send to / pure-data normalization,” never just “Next.” The Node-RED 5.0.2 node documentation states explicitly that Links cannot connect into or out of a Subflow.

Link Call is the mode that waits for an answer. It sends a message to a specified Link In, and the callee path must end at a Link Out configured in return mode. Using internal call-origin data, that return sends the message back to the original Link Call, and only then does the Link Call emit it from its own output. An ordinary “send to all” Link Out does not complete a Link Call — it is a different node mode entirely, and confusing the two is the single most common reason a call hangs.

sequenceDiagram
  participant LC as "Call / offline doubling (static Link Call)"
  participant LI as "Callee / offline doubling (Link In)"
  participant FN as "Validate and double (Function)"
  participant LO as "Return / offline doubling (Link Out, return mode)"
  LC->>LI: msg.request = requestId + value
  LI->>FN: forward the message
  FN->>LO: msg.response = requestId + doubled
  LO-->>LC: return, closing this one call

Build this exact chain once, offline, and the difference between a wire and a return stops being theoretical.

1. Step 1

   Create the manual request entry point

   On an isolated tab, add an Inject node named Manual call LC-001. Set the payload type to number, value 4. Under properties add the string msg.requestId = "LC-001", set once to false, and leave repeat and crontab blank. Connect it to a Change node named Build request contract that uses JSONata to set msg.request to {"requestId": requestId, "value": payload}, then deletes msg.payload.

2. Step 2

   Configure a static Link Call

   Add a Link Call named Call / offline doubling. Choose the static call type, set the timeout to 2 seconds, and explicitly select the Link In from the next step as the target — do not use msg.target here. The wiring must read: “Manual call LC-001” → “Build request contract” → “Call / offline doubling.”

3. Step 3

   Create the named callee path

   On a different, regular flow tab, add a Link In named Callee / offline doubling. Connect it to a pure Function named Validate and double, then to a Link Out named Return / offline doubling with its mode set to return. The Function reads no context and performs no external I/O:

   const request = msg.request;
if (!request || typeof request.requestId !== "string"
|| typeof request.value !== "number" || !Number.isFinite(request.value)) {
node.error("INVALID_REQUEST", msg);
return null;
}
msg.response = {
requestId: request.requestId,
doubled: request.value * 2
};
return msg;
4. Step 4

   Observe the normal response and the timeout separately

   Connect the Link Call's output to a Debug node named Inspect response that shows only msg.response. Add a Catch node named Catch Link Call timeout, scope it only to “Call / offline doubling,” and connect it to a Debug node showing only msg.error. Press Inject once for the normal test: the only projection you should see is {"requestId":"LC-001","doubled":8}, and Catch receives nothing. To test the timeout, temporarily disconnect only the wire from “Validate and double” to the return Link Out. After 2 seconds, Catch reports msg.error.message as timeout, with source type link call and source name “Call / offline doubling,” and the normal Debug receives nothing. Reconnect the return wire immediately after the test.

5. Step 5

   Verify, clean up, and export

   Confirm the complete path reads exactly: manual Inject → Change/request contract → static Link Call → named Link In → pure transform → return Link Out → limited Debug. It contains no Action, HTTP, MQTT, file, scheduling, or credentials node. Clear the Debug messages, make the smallest possible export, and review it as text before you do anything else with it.

Late returns are not cancelled

In Node-RED 5.0.2, the default Link Call timeout is 30 seconds — the walkthrough above shortens it to 2 seconds purely to make waiting bearable. When the timeout expires, the pending request is removed and the error mechanism fires, which is what lets a Catch node receive it. A timeout neither cancels the work nor suppresses a late return. If the return arrives after the timeout, the pending record is already gone, so the Link Call simply emits the message as ordinary downstream output. Both your timeout-compensation logic and your ordinary downstream logic must therefore assume that either path, or both, can run. Never build on the assumption that only one of them fires.

flowchart TD
  A["A return arrives carrying
msg.response.requestId"] --> B{"Does it match
flow.activeLinkRequestId?"}
  B -->|"yes, it matches"| C["Clear the active ID.
Pass the message on"]
  B -->|"no match, already cleared"| D["Return null.
The late return is dropped here"]

Constrain dynamic targets

msg.target must never come directly from untrusted input. Version 5.0.2 resolves a dynamic target in a fixed order, and the further down that order it has to search, the more room there is for an ambiguous match.

If your target set is fixed, prefer a static target outright, or map the operation through an explicit allowlist in the node before the Link Call — never let a caller-supplied string become the target string directly.

Every instance gets its own node context. Nothing else is automatic

A Subflow is a reusable internal graph of nodes. Each time you drag it onto a flow you create an instance, and a change to the Subflow's definition affects every instance at once — which is why a Subflow suits “the same algorithm with different non-secret parameters,” not copies you actually want to diverge over time. The nodes inside each instance are distinct runtime instances, and their node context should be treated as isolated by default. Deliberately reading or writing the parent flow's context from inside a Subflow crosses that boundary on purpose, and it needs to be documented as such.

Subflow properties become environment values for a given instance, which is where non-sensitive parameters like DISPLAY_LABEL or MAX_COUNT belong. A Function retrieves one with env.get("DISPLAY_LABEL"), and a typed input field can select the environment-variable type directly. The runtime also exposes instance information such as NR_SUBFLOW_ID, NR_SUBFLOW_NAME, and NR_SUBFLOW_PATH, which help you tell instances apart while diagnosing — but IDs and paths like these must not turn up in a public example or a shared record.

Run two instances of that Function and each instance's seen count starts at 1, independently, because node context is scoped per instance. If a requirement genuinely calls for shared statistics, document the shared state's lifecycle first, then deliberately choose flow or global context — never reach for one simply because it happens to be reachable. A Subflow can read its parent's context or environment through $parent., but doing so increases coupling and belongs in the interface documentation, not buried in a Function. Even when a Context store uses localfilesystem, an assignment does not necessarily become durable the instant you make it. Context, in every case, is not a secret store either.

flowchart TD
  P["Parent flow context"]
  A1["Instance 1: Function node"] --> C1["Instance 1's own node context
seen = 1, then 2, then 3 ..."]
  A2["Instance 2: Function node"] --> C2["Instance 2's own node context
seen = 1, then 2, then 3 ..."]
  A1 -.->|"only if the code says $parent."| P
  A2 -.->|"only if the code says $parent."| P

Never let a Subflow contain itself

Do not place a Subflow instance directly inside its own definition, and do not create a cycle where A contains B and B contains A. This is not ordinary function recursion with a base case that eventually stops it — it builds an architecture that cannot be expanded safely and creates a real resource risk. For anything that needs repeated processing, use bounded message iteration or a finite-state design instead, and test its termination condition explicitly before you trust it.

Portable is not the same thing as safe to hand to someone else

In everything above, environment variables are for non-sensitive, replaceable configuration only — display text, a batch limit, that kind of value. Do not put tokens, passwords, private keys, or connection credentials into flow JSON, Subflow properties, Function code, Debug output, or Context. Environment-variable names and values can themselves be exposed through exports, diagnostics, or the runtime environment. Simply “using env” does not make a secret secure; it just moves where the secret is sitting in plain text.

The Library is a reusable store inside the editor: save flow snippets or Function code and retrieve them later. Import/export serializes the current selection to JSON, or brings JSON into the editor, which suits an explicit, one-time transfer. Projects gives you a complete Git-backed working directory with a repository, branches, remotes, and a Git identity. None of the three replaces a managed backup, and none of them scrubs secrets for you.

Once Projects is enabled, access to Git remotes and Git credentials becomes another security boundary of its own. The standard Projects workflow in Node-RED 5.0.2 adds an encrypted project credentials file to version control. That is expected behavior, and it does not make the file safe to publish — access to the project repository and its full history both need to stay restricted. Every project has its own project credential secret. Back it up securely, separately from the repository, or the encrypted credentials become unrecoverable the day you lose it.

The add-on's own credential_secret is ignored in Projects mode and cannot decrypt project credentials. The project repository, the project credential secret, your Git access credentials, and a complete add-on backup are four different things that each serve a different purpose. Git history is not a complete backup of the runtime environment, and an add-on backup does not replace auditable version history either.

The pre-sharing scrub checklist

Flow JSON is readable and comparable, which is exactly what makes it easy to carry environment details somewhere they should not go. Start an export from the smallest possible selection; do not select an entire workspace for convenience. If a snippet depends on a configuration node, document the type of configuration it requires rather than keeping a real production ID inside it.

• No credentials block, token, password, private key, cookie, Authorization value, or webhook identifier.
• No real URL, hostname, IP address, Home Assistant server/entity/device/area ID, MQTT client ID, or topic.
• Every configuration-node reference identified; in the target environment, reselect an approved configuration node through the editor rather than editing a JSON ID by hand.
• No Inject set to run at startup, no schedule, listener, external connection, file write, or action path left live; if the snippet keeps an operational node, disable it before export and document why.
• Every Function, Template, Change, JSONata expression, Comment, node name, and flow description reviewed character by character.
• Only required wires remain; Link targets, Subflow definitions, and instance properties are complete and contain no recursion.
• The JSON inspected as plain text, then imported into a blank, isolated tab, with node count, types, disabled state, and configuration dependencies verified there.

Before importing unknown JSON, read type, wires, d, the Inject node's once setting, and every configuration field in a plain text viewer first. If a node type is reported missing, do not install a package just to clear the warning — verify the source, the pinned version, and whether you actually need it before you add anything.

The least data, for the shortest time, at the lowest frequency

A Debug node can show a selected message property, the complete message, or the result of a JSONata expression in the Debug sidebar. It can also write output to the runtime log, or show a short value as the node's own status. Its default is msg.payload. The sidebar's structured view makes objects and arrays easy to expand and can jump from source information straight to the node on the canvas — convenient, but that convenience is not a reason to leave it outputting everything indefinitely.

A complete msg can carry locations, notification text, Home Assistant entity data, live HTTP objects, or other environment-specific information you never meant to expose. Content sent to the runtime log leaves the sidebar's temporary context behind and may land in a centralized collection and retention system with its own rules. Stack traces can likewise reveal file paths or sensitive content, so sanitize them before you share one with anybody.

Three different questions, and none of them is Debug's question

A green status beneath a node does not mean the message it just processed succeeded. An expected payload in Debug does not mean every downstream node has finished. A Complete event does not mean all downstream work has finished either. These four core nodes observe four different events, and conflating any two of them is how a false signal of success gets into a change record.

flowchart TD
  F["Function node:
Generate a finite diagnostic event"]
  F -->|"ordinary return msg"| D["Debug reads msg.payload"]
  F -->|"node.error(msg) on failure"| C["Catch reads msg.error"]
  F -->|"node.status() call"| S["Status reads msg.status"]
  F -->|"node.done() call"| X["Complete reads msg.complete"]

When the runtime creates a Catch message it adds msg.error. If the original message already had an error property, that existing value moves to msg._error instead of being overwritten silently. Business data should never appropriate the reserved meaning of msg.error for its own use. A Status node explicitly creates no payload; downstream nodes need to read msg.status rather than carry over payload assumptions from an ordinary data path.

Catch: only catchable errors

A Catch node receives an error only when a node reports it through the runtime's error mechanism while processing a message. Inside a Function node, call node.error(message, msg) with the original message to make an error catchable. Calling only node.error(message), without the message, does not associate the error with that msg for a Catch node to pick up. As a rule, report a validation failure explicitly and stop processing there — do not emit a success result and an error together.

By default, Catch captures errors from nodes on the same tab. You can instead select specific nodes, or capture only errors an already-targeted Catch has not handled. If an error matches several Catch nodes, every match receives it — which means several error-handling paths can duplicate the same work if you are not careful. An error inside a Subflow is handled first by a Catch inside that Subflow, and only propagates out to the tab holding the instance if nothing internal matches. A third-party node failure, a connection condition, an empty output, or a business-level rejection is not automatically a catchable error — check the node's own contract and verify its behavior rather than assuming.

Status: what nodes actively publish

A Status node receives status messages published by nodes on the same workspace tab by default, or you can select individual nodes instead. Its output carries msg.status.text plus the source type, id, and name; it never creates a payload. A node showing “connected,” “waiting,” or a color change is reporting only the status that node chose to publish — not proof that any particular business message succeeded.

Complete: one node's own completion, not the whole path's

A Complete node triggers when a selected node tells the runtime, “I have finished processing this message.” Node-RED 1.0 introduced this through the node completion API, and the node's own implementation has to call done when its work — synchronous or asynchronous — actually finishes. Not every node supports it, so the absence of a Complete event does not by itself prove failure.

Complete requires you to select the nodes you want to watch, unlike Catch's whole-tab default. It is useful for a node with no output port that still implements completion, or for turning the end of one node's processing into a separate internal control path. It proves only that “the selected node declared completion.” It does not prove every downstream message that node previously sent has finished processing, and it does not prove an external system has completed its part either.

A Function node's synchronous path can use return msg directly. Its asynchronous mode normally calls node.send(msg) and then node.done() once the work has truly ended. Function nodes also carry On Start / On Stop lifecycle hooks for initializing or cleaning up resources at deployment and shutdown boundaries — and that lifecycle code needs its own error, timeout, and cleanup strategy too, not treatment as unbounded background work. This part deliberately skips timers and external-I/O examples so an asynchronous demonstration cannot leave residual work behind for you to clean up later.

Run the reproducible example

The downloadable example 11-debug-catch-status.json contains exactly one Complete node, named “Observe Function completion,” scoped only to the core Function node “Generate a finite diagnostic event.” Complete, Catch, and Status all start disabled with d: true. Complete connects to its own Debug node, “Inspect complete,” which projects only msg.complete and stays entirely separate from the two Debug nodes that project msg.error and msg.status.

1. Step 1

   Read it as text first

   Confirm it contains 12 nodes, that all three Inject nodes use once=false with repeat and crontab left blank, and that the Function node has no lifecycle hooks, modules, timers, or I/O.

2. Step 2

   Enable only Complete, and click once

   Import an isolated copy, enable Complete only, and leave Catch and Status disabled. Click “Manual test: normal output” once. Do not replace it with a startup or scheduled Inject.

3. Step 3

   Confirm the two exact projections

   The ordinary Debug node receives exactly {"caseName":"normal","doubled":8}. The Complete Debug node receives exactly {"source":{"id":"b000000000000005","type":"function","name":"Generate a finite diagnostic event"}}. That second value is a projection of msg.complete, not a complete message, and it does not mean the downstream Debug node has itself finished.

4. Step 4

   Restore Complete, then test the other two, one at a time

   Immediately set Complete back to d: true after the test. Enable only the corresponding observer for each of the remaining paths. The Catch Inject makes the error Debug receive message TEST_ERROR with a source pointing to the same Function inside msg.error. The Status Inject makes the status Debug receive fill blue, shape dot, text TEST_STATUS, with a source pointing to that Function inside msg.status. Neither path produces any ordinary payload output.

Mock first, then Context, then a Subflow or Link boundary

Flow testing does not need to start with a live installation. Fix the input shape with a mock message first, then gradually introduce Context, Subflow, or Link boundaries one at a time. A mock is not meant to reproduce every piece of environmental data — it proves the logic with the fewest fields necessary. Unknown fields, missing values, boundary values, and the wrong type each need to become their own explicit test case, not an afterthought.

Invariants, not just payload comparisons

• Input msg.topic, msg._msgid, and other designated metadata are not overwritten unexpectedly.
• An error case is never also sent to the success output.
• Each input produces no more outputs than the contract permits, and is not processed twice because two Catch nodes both matched.
• Context keys and their contents stay bounded; state after a redeploy matches the design, not a leftover from before.
• Every timeout, retry, and buffer has an upper bound; the mocks used in this part create no queues, timers, or external I/O of their own.

At minimum, test a missing payload, null, a string in place of a number, NaN or infinite values, values outside the permitted range, extra fields, duplicate messages, and messages arriving out of order. For Link Call, also test a missing return. For a Subflow, interleave two instances. For Catch, test a pre-existing msg.error. For Status, test downstream code that misreads the payload. For Complete, test an unselected node and a node that does not support completion at all.

Do not use a visual impression of the Debug sidebar as your only evidence. Put case tables, expected fields, and result summaries — with no environment data — into the change record instead. Real secrets, complete messages, stack traces, and runtime logs do not belong in a general-purpose ticket.

Deployment scope and regression scope

Node-RED 5.0.2 gives you three deployment scopes: Full, Modified Flows, and Modified Nodes. Full restarts every node. Modified Flows restarts any flow containing a changed node. Modified Nodes restarts only the nodes actually modified. A smaller scope reduces unrelated restarts, but it does not automatically guarantee safety on its own. Work out first whether the change touches Subflow instances, the users of a configuration node, Context, or any other shared path, and only then choose the smallest scope that is genuinely sufficient.

Before every deployment, record a recoverable version and inspect startup Inject nodes, schedules, listeners, and any node with an external side effect. After deployment, run one pure-data smoke case first, then the regression tests for the current fix and its adjacent flows. If a configuration-node or shared-Subflow change affects several flows, do not shrink the scope you actually deploy just to claim the smallest label.

The failures that actually happen, matched to the fix

The ones that come up again and again

Where to go from here