Node-RED Subflow Error
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
- Using
foldlinstead offoldl'causing stack overflow on large lists - Forgetting
deriving (Show, Eq)on custom data types needed for debugging - 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
DodaTech — subflows that flow smoothly.
Built by the developers of DodaTech
Doda Browser, DodaZIP & Durga Antivirus Pro