Question
credentialSecret compatibility boundary: restoring Node-RED flows without the original secret
Ira Indigo
0 reputation · 26 Aug 2023, 01:33 UTC
92.1K views
Loading…
0 reputation · 26 Aug 2023, 01:33 UTC
Assuming a recent Node-RED runtime, migrating an instance between environments or restoring from backup may leave flows containing encrypted credentials generated under a different credentialSecret. The runtime does not validate during restore whether those encrypted values can be decrypted with the currently configured secret, so credential nodes appear present but may remain non-functional until a flow executes. This creates a compatibility boundary that is not obvious from the flow JSON alone.
The uncertainty increases when a Projects-enabled backup is restored to a standard non-Projects runtime, because the backup includes Git metadata and a package.json that alter how node modules and flows are managed. During that transition, the admin API deploy endpoint replaces the active flow configuration but does not restart the Node-RED process, meaning changes to settings.js or environment variables require a full restart to take effect. It is unclear whether any documented mechanism exists to surface decryption failures at deploy time rather than at runtime.
Given this boundary, what is the intended behavior when a restored flow references credentials encrypted under a different credentialSecret? Does the runtime provide any pre-deployment validation for credential decryptability across a Projects-to-standard migration? If not, what is the documented approach for confirming that a restored instance is fully operational before relying on credential-dependent nodes?
When a flow is restored to a Node-RED instance that uses a different credentialSecret, the encrypted credential values cannot be decrypted because the runtime only decrypts them at execution time. This creates a hidden compatibility boundary that is not evident from the flow JSON alone.
\nIs the original credentialSecret still accessible for the restored instance, or must the secrets be re‑entered manually?
Use comments to ask for clarification. Post a solution as an answer.
35,275 reputation · 26 Aug 2023, 12:59 UTC
Node-RED 3.x+ emits a single WARN Failed to decrypt credentials for node <id> line at process startup when it first loads flows.json. This warning is not re-emitted on subsequent admin API POST /flows deploys — only a full restart re-triggers the check. The warning includes only the internal node ID, not the node name or type, and is rate-limited so it can be missed in busy logs.
For Projects-to-standard migrations, the backup's flows_cred.json is ignored; credentials must be inline in flows.json. If the source and target credentialSecret differ byte-for-byte (including any trailing newline from secret stores), every credential becomes permanently undecryptable unless re-entered manually.
The documented operational check remains: restart the runtime, grep logs for "Failed to decrypt", then manually exercise each credential-dependent node. No pre-deploy validation endpoint exists in any current release.
nodered