# Documenting Node-RED flow failures: a repeatable checklist for bug reports and handoffs

**URL:** <https://discourse.nodered.org/t/documenting-node-red-flow-failures-a-repeatable-checklist-for-bug-reports-and-handoffs/101521>\
**Category:** General\
**Created:** [24 July 2026 06:31 UTC](https://discourse.nodered.org/t/documenting-node-red-flow-failures-a-repeatable-checklist-for-bug-reports-and-handoffs/101521 "2026-07-24T06:31:46Z")\
**Posts on this page:** 1\
**Page:** 1

<div class="post-metadata">

**Author:** ![anon10594671](https://avatars.discourse-cdn.com/v4/letter/a/f05b48/32.png) [@anon10594671](https://discourse.nodered.org/u/anon10594671)\
**Post date:** [24 July 2026 06:31 UTC](https://discourse.nodered.org/t/documenting-node-red-flow-failures-a-repeatable-checklist-for-bug-reports-and-handoffs/101521/1 "2026-07-24T06:31:46Z")

</div>

Anyone who has filed or received a bug report knows the pattern: "it doesn't work" followed by a screenshot of a red dot on a node. That's rarely enough to reproduce anything. If you maintain flows for a team, contribute to community threads, or just want your own future self to understand what happened six months from now, it helps to have a consistent way of documenting a failure the moment it happens.

Here's a workflow that has worked well for capturing Node-RED issues in a form that's actually reusable.

**1. Export the minimal reproducible flow, not the whole tab.**  
Before anything else, isolate the nodes involved. Select just the relevant subflow, use Export (Ctrl/Cmd+E), and copy only that JSON. A ten-node reproduction is far more likely to get read and tested than a 300-node production flow with three unrelated subflows attached. If credentials or config nodes are involved, strip or redact them before sharing — exported JSON can carry more context than you expect, including flow variable values if you're not careful.

**2. Capture debug output as text, not just a screenshot.**  
Screenshots of the debug sidebar are common but limited — they can't be searched, diffed, or pasted into a fix. Instead, right-click the debug message and use "Copy the object" or expand it and copy the raw text. Paste that into a code block alongside the exported JSON. If timing matters, note the wall-clock time or the msg timestamp so a reviewer can line up the debug output against the flow structure.

**3. Note the environment constraints.**  
A failure that only appears under specific conditions is a different problem than a general one. Record:

- Node-RED version and Node.js version
- Relevant node/module versions (dashboard, contrib nodes, etc.)
- Whether it reproduces on a clean install with just core nodes
- Any timing, load, or concurrency conditions (e.g., only after N messages, only on cold start)

This is the part people skip most often, and it's usually the difference between someone reproducing your issue in five minutes versus giving up.

**4. Write a short, literal sequence of what you did.**  
Not "deploy and it breaks," but the actual click order: deployed, injected a manual trigger, waited 3 seconds, second message arrived malformed. Vague descriptions force the reader to guess at the reproduction path, which is where most back-and-forth in support threads comes from.

**5. Add a short visual walkthrough when the failure is timing- or UI-related.**  
Some failures are hard to convey in text alone — a dashboard widget that flickers, a race condition visible only as the debug panel updates, or a sequence of node status changes. A short screen recording is often more efficient than a paragraph of description, and it removes ambiguity about what actually happened versus what the reporter assumed happened.

**Limitations worth keeping in mind.**  
This workflow won't help with truly non-deterministic issues, and no amount of documentation replaces a minimal reproduction when timing-sensitive hardware or external APIs are involved — sometimes the honest answer is "intermittent, environment-dependent, can't isolate further yet," and that's a legitimate status to report rather than force a false reproduction. Redacting credentials and being mindful of what your debug output actually contains also takes a bit of discipline every time, not just the first time.

None of these steps are exotic, but doing all of them consistently — export, debug text, environment, sequence, and an optional visual when it clarifies more than text — turns a frustrating back-and-forth into something a reviewer can act on immediately.