Node-RED Projects vs manual flows-file backup: which rollback path preserves credential decryption?

Question

Node-RED stores flow credentials in a separate encrypted file tied to a credentialSecret, so rolling back a flow after a node configuration change risks leaving nodes unable to decrypt their credentials. The documented rollback paths are Projects, which wraps the flows file in a local Git repository with commit-based history and branch switching, and manual backup of the flows_<hostname>.json file alongside its _creds counterpart.

The unresolved decision is whether credentialSecret must remain constant across commits and branches for a rollback to be safe. Projects does not enforce this: if the secret changes, or a restored project's credentials were encrypted under a different key, decryption fails and nodes silently lose authentication until credentials are re-entered. Manual file copies avoid Git dependency but risk restoring a flows file whose node configuration no longer matches the saved credentials.

Should the encryption key be treated as an invariant pinned across every commit and branch, or is re-entering credentials after a secret change an accepted cost of the Projects workflow? Does the editor's branch-switching prompt for uncommitted changes change the recovery-point objective when the credentials file is excluded from the tracked project?

Muntasir · Answer

Direct Answer Manual backup of both flows_.json and flows__creds.json preserves credential decryption only if the credentialSecret has not changed. Node-RED Projects (Git-backed) does not preserve credentials on rollback because the _creds file is excluded from version control by default. Why This Happens Confirmed Behavior Credentials are encrypted with AES-256-CTR using a key derived from credentialSecret (via PBKDF2). The _creds file stores only the encrypted payload and salt. Projects tracks flows.json in Git but .gitignore excludes flows_*_creds.json. Branch switches or historic commits restore flow topology, not the encrypted credentials. If credentialSecret changes between commits, any restored _creds file (from any source) becomes undecryptable. Nodes show "credentials not set" and require re-entry. The editor warns only about uncommitted flow changes during branch switching; it never prompts for credentialSecret changes. Likely Explanation Treating credentialSecret as project state (something that can vary per commit/branch) breaks the encryption contract. The secret is infrastructure configuration — like a TLS certificate — and must remain constant across the entire deployment lifecycle. Steps for a Safe Rollback Pin credentialSecret in settings.js (or via NODE_RED_CREDENTIAL_SECRET env var). Never generate it at startup. Back up the secret separately (password manager, sealed secret, Vault). Do not commit it. For manual rollback: copy both flows_.json and flows__creds.json from the same point in time. Verify the secret matches the one used when the backup was made. For Projects rollback: after git checkout , you must also restore the matching _creds file from an external backup. Git alone cannot do this. Verify at deploy: check Node-RED logs for "Credentials file decrypted successfully". If you see "Failed to decrypt credentials", the secret or _creds file is mismatched. Recovery-Point Objective Impact Because _creds is excluded from Git, the RPO for credentials is not tied to commit history. It is bound to your last manual _creds backup (or external secret store snapshot). Branch-switching prompts only protect flow topology, not authentication state. One Diagnostic Detail Needed Are you using an external secret store (HashiCorp Vault, AWS Secrets Manager, etc.) via Node-RED 3.x+ credentialSecret function, or is the secret stored statically in settings.js/env? This changes whether secret rotation is even possible without re-entering credentials.

Node-RED Projects vs manual flows-file backup: which rollback path preserves credential decryption?

1 answer

Direct Answer

Why This Happens

Confirmed Behavior

Likely Explanation

Steps for a Safe Rollback

Recovery-Point Objective Impact

One Diagnostic Detail Needed

Your perspective belongs here.

0 question comments