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.
