Skip to content

Node-RED Subflow Error

DodaTech Updated 2026-06-24 3 min read

In this tutorial, you'll learn about Node. We cover key concepts, practical examples, and best practices.

Hook

You create a subflow to reuse a common pattern (e.g., MQTT processing + validation + formatting). You use it in multiple places. But when a message passes through a subflow instance, it emerges corrupted or the subflow throws an error that you cannot trace.

The Wrong Way

Editing the subflow's internal nodes while flows are running can cause race conditions where some invocations use the old logic and others use the new logic.

# BAD: Editing subflow while deployed
# Open subflow → Change function → Deploy immediately
Subflow updated
Some instances ran with old code, some with new
Inconsistent results across parallel flows

Subflow changes apply globally to all instances. Deploy during low-traffic periods.

The Right Way

Verify subflow inputs and outputs and debug a single instance before deploying changes.

# 1. Check subflow input/output definitions
# In the editor: Subflow → Properties → Check:
# - Inputs: name and type of each input
# - Outputs: name and type of each output
# 2. Add Debug nodes inside the subflow for testing
# Open the subflow → add Debug node at each stage
// 3. Check subflow function nodes for proper return values
// Inside subflow, ensure each path returns a message
if (condition) {
    // Process
    return [null, msg];  // Output 2
} else {
    // Error
    return [msg, null];  // Output 1
}
# 4. Test with a clean inject
[Inject] → [Subflow instance] → [Debug node (output 1)]
                           → [Debug node (output 2)]
# 5. Check for environment variable conflicts
# Subflow environment variables override flow variables with the same name
# 6. If subflow crashes Node-RED, check the server log
journalctl -u node-red -n 50 --no-pager | grep "subflow"
[error] [subflow:MySubflow] TypeError: Cannot read properties of undefined (reading 'payload')

The subflow expects msg.payload but receives undefined.

// Add input validation at the start of the subflow:
if (msg === undefined || msg.payload === undefined) {
    node.warn("Subflow received invalid message");
    return;
}

Prevention

  • Define clear input/output contracts for subflows.
  • Add a Debug node inside the subflow for the first input and last output.
  • Use environment variables for subflow parameters instead of hardcoded values.
  • Test subflows in isolation before using in production flows.
  • Document what each subflow expects and returns in its properties.

Common Mistakes with red subflow error

  1. Using foldl instead of foldl' causing stack overflow on large lists
  2. Forgetting deriving (Show, Eq) on custom data types needed for debugging
  3. Placing the wildcard pattern first in case expressions, making all subsequent patterns unreachable

These mistakes appear frequently in real-world NODE code. DodaTech's contributors have identified these patterns through analysis of open-source projects and production systems.

Practice Exercise

Write a pure function that safely divides two integers using Maybe, then test it with edge cases like division by zero and negative numbers.

This exercise reinforces the concepts covered in this guide. Try implementing it before checking online solutions.

FAQ

Can a subflow call another subflow?

Yes — subflows can be nested. However, deeply nested subflows (3+ levels) become hard to debug. Prefer flat subflow hierarchies.

How do I pass configuration to a subflow?

Define environment variables in the subflow properties. Set their values per-instance in the subflow's configuration panel. Access them with env.get("VAR_NAME") inside function nodes.

Why does editing a subflow affect running instances?

Subflows are templates — all instances share the same internal flow. Any change to the template is immediately reflected in all instances on the next deploy. There is no version pinning per instance.


DodaTech — subflows that flow smoothly.

Built by the developers of DodaTech

Doda Browser, DodaZIP & Durga Antivirus Pro