Persist Node-RED Flow and Global Context Across Restarts

Problem and expected outcome

Node-RED keeps flow context and global context in memory by default. When the process stops, crashes, or redeploys, those values disappear. If a flow tracks a counter, a device state, or a form step, the value resets on restart.

File-based context storage writes context values as JSON files to a directory you control. The useful takeaway is that you can enable this storage in Node-RED's settings file, restrict values to JSON-serializable data, and verify that a counter continues from its pre-restart value after a full Node-RED restart.

Prerequisites

• A running Node-RED instance. This guide assumes Node-RED 3.x.
• Filesystem access to the Node-RED settings file, typically settings.js.
• Permission to create and write to a context directory on the host running Node-RED.
• A text editor and a terminal or command prompt on the Node-RED host.

Configure file-based context storage

Open settings.js in a text editor. Common locations are ~/.node-red/settings.js on Linux or macOS, %USERPROFILE%\.node-red\settings.js on Windows, or /data/settings.js in many Docker deployments. Run commands in a terminal on the host where Node-RED runs, using the user account that owns the Node-RED process.

Create a writable context directory. Example:

mkdir -p /home/youruser/.node-red/context
chmod 700 /home/youruser/.node-red/context

chmod 700 restricts the directory to the owner only. Replace /home/youruser/.node-red/context with a path appropriate for your installation.

In settings.js, find or add the contextStorage block and set file as the default store:

contextStorage: {
    default: "file",
    file: {
        module: "localfilesystem",
        dir: "/home/youruser/.node-red/context"
    }
},

If you omit dir, Node-RED uses its default contexts folder under the user directory. Save the file and restart Node-RED so the new storage setting loads at startup.

Risk: A syntax error in settings.js can prevent Node-RED from starting. Keep a copy of the original file before editing.

Store and read a context value

Use flow.get and flow.set for values scoped to one flow. Use global.get and global.set for values shared across all flows.

Example Function node:

let count = flow.get("counter") || 0;
count += 1;
flow.set("counter", count);
return { payload: count };

Wire an Inject node to the Function node, and a Debug node to the output. Each Inject increments the stored counter and displays the result.

Writing to context does not automatically trigger downstream nodes. A separate Inject, status change, or message flow must read the stored value or act on it.

Verify persistence across restart

1. Deploy the flow in Node-RED.
2. Click the Inject node several times. Note the number shown in the Debug sidebar.
3. Restart the Node-RED process, not just the flow. For example, restart the system service, Docker container, or terminal session running Node-RED.
4. Click the Inject node again. If the counter continues from the pre-restart value, file-based persistence is working.
5. List the context directory to confirm JSON state files were written:

ls -la /home/youruser/.node-red/context

Expected check: the directory contains JSON files corresponding to the flow or global keys you set. Do not expect a specific filename; Node-RED names files based on the store and key.

If state is lost after restart

• Check the Node-RED startup log for the active settings file path. A wrong path means Node-RED may still be using in-memory storage.
• Confirm the Node-RED process user can write to the context directory. Test by creating a temporary file there as that user.
• Confirm default is set to "file" in settings.js, not "memory".

Limitations and safe usage

• Only JSON-serializable values can be persisted reliably. Do not store functions, promises, streams, Buffers, or circular objects.
• File context storage is not a database. Avoid high-frequency telemetry, large payloads, or many keys because file I/O and file count can degrade performance.
• Multiple Function nodes writing the same context key concurrently can race. Designate one writer per key or coordinate reads and writes explicitly.
• Node-RED does not encrypt context files by default. Protect the context directory with filesystem permissions and encryption at rest if it holds sensitive payloads.

Rollback

Because editing settings.js changes runtime state, you can roll back by restoring the original settings file and restarting Node-RED. Context falls back to in-memory storage. Values already written to the context directory remain on disk but are unused until file-based storage is re-enabled.