Prepare for n8n 3 by updating to the latest stable 2.x, resolving the Migration Report, and proving that a full backup restores on an isolated instance. As of 1 November 2026, n8n 3.0 is a beta released on 27 October; stable is expected in early December. Treat that as a plan, not a completed release. Check the official announcement before scheduling production work.
The useful work today is compatibility and recovery preparation. n8n says 2.x will receive security and critical bug fixes for 12 months after the stable 3.x release. That gives teams room to rehearse rather than putting a beta directly in charge of invoicing, customer emails or order processing.
Start with the Migration Report on n8n 2.x
The report is available from version 2.39 under Settings > Migration Report. First update to the latest stable 2.x release through your existing maintenance procedure. Read its release notes and back it up too; reaching a preparation version is still an upgrade. n8n's update guidance recommends testing updates before applying them to production.
Open the report as an instance owner or administrator so you can inspect instance settings as well as workflows. Other users see only workflows they can edit. Work through upgrade blockers and execution failures first, then behavior changes. Export the CSV and assign each important workflow a named person and a repeatable acceptance check.
For supported issues, automatic migration saves a new workflow version; the published version keeps running until you publish the replacement. Review the changes, test the output and publish deliberately. A migration that replaces a node does not prove that your branching, dates or external actions still mean the same thing. These behaviors are documented in the migration tool guide.
A practical triage order is payment-related workflows, customer-facing notifications, time-sensitive imports, and then internal convenience automations. Include rarely used month-end and annual jobs. Low recent execution counts are not a reliable measure of business importance.
Check the changes that affect operations
The official breaking-change list is the authority for your installed beta or eventual stable release. Start with these concrete checks:
| Change in 3.0 | What to review |
|---|---|
| Docker-based self-hosting | Move npm or npx installations to a supported container deployment. |
| Legacy nodes removed | Replace Function and Function Item with Code; Cron and Interval with Schedule Trigger. |
| Shorter Code task timeout | Review long-running scripts; the default changes from five minutes to one. |
| Unverified community packages disabled by default | Inventory installed packages and their workflow dependencies. |
| Slack signing secret required | Check affected credentials and signed event delivery. |
Do not combine containerization, database-engine upgrades, host relocation and the n8n major upgrade in one maintenance window unless you have rehearsed the combined operation. Separating those changes makes a failure easier to diagnose and recovery easier to reason about. Record the exact image tag and digest used in every rehearsal so the production candidate can be compared with it.
Queue mode needs worker-level checks
In 3.0, manual executions in queue mode run on workers. Verify that workers have the network routes, mounted files, packages and secrets required by workflows previously exercised from the editor. A manual test that succeeds on a differently configured process can hide a deployment problem.
The queue-mode documentation requires the same encryption key across main, worker and webhook processes. It also states that filesystem binary-data storage is not supported in queue mode. Therefore, check binary persistence before assuming that adding workers and a shared directory is sufficient.
For n8n's built-in external binary storage, verify licensing: the external-storage documentation lists self-hosted Business and Enterprise availability. It officially supports AWS S3; other S3-compatible services are not officially supported by n8n. Uploading a backup archive to object storage is a separate use case from configuring n8n's runtime binary backend.
Build a backup that can recover the instance
Workflow JSON is useful, but it is not a full server backup. n8n's backup and restore guide identifies the user folder, external database, custom-node directories and any external or custom-path binary and execution storage as parts of a complete backup.
- Database: the SQLite database or a consistent PostgreSQL backup, depending on your installation.
- User folder: the actual persistent
.n8ndirectory, including configuration. - Secrets and deployment configuration: encryption key, database connection settings, storage settings and the exact previous image.
- Additional state: binary files, execution files and custom extensions wherever you configured them.
With SQLite, stop n8n before copying its database files unless you use a tool that takes a consistent SQLite snapshot. For PostgreSQL, use database-aware backup tooling. For a migration recovery point, pause writers so the database and attached file storage describe the same application state. Include every worker and webhook process in that plan.
Keep a small backup manifest outside the server being upgraded. For example:
Backup set: pre-n8n3-rehearsal
Application: exact n8n 2.x image tag and digest
Database: snapshot or dump identifier
User folder: archive identifier
Binary storage: archive or snapshot identifier
Configuration: protected secret-store reference
Encryption key: protected recovery reference
Restore destination: isolated instance identifier
Restore result: date, operator, acceptance checksThis is an example record, not a backup script. Populate it with actual identifiers after the artifacts exist. Store encrypted backups separately from the live host and verify that another authorized operator can retrieve the key without relying on that host. A checksum helps detect a damaged transfer; it does not establish that credentials can be decrypted or workflows can execute.
If PostgreSQL backs your instance, our PostgreSQL backup guide explains the database side. Keep retention decisions separate from your upgrade deadline: the required recovery point must survive cleanup jobs during the observation period.
Add portable exports without confusing them with recovery
The Server CLI provides workflow and credential exports. Inside your existing container, use a persistent backup mount; this example assumes your Compose service is named n8n and a protected host backup directory is mounted at /backups:
docker compose exec -T -u node n8n \
n8n export:workflow --backup --output=/backups/workflows/
docker compose exec -T -u node n8n \
n8n export:credentials --backup --output=/backups/credentials/Use separate directories and a fresh backup set. Confirm ownership and write permissions before running the commands. Do not assume an arbitrary path inside a container persists after recreation. These exports help inspect and move workflows, but omit instance-level state such as users, settings and execution history. Avoid --decrypted for routine backups: it writes credential secrets in plain text.
A database backup without its encryption key is incomplete
n8n encrypts credentials before storing them. The original key is generated into the user folder or supplied through N8N_ENCRYPTION_KEY. Recover the existing value through your protected configuration process; generating a new one does not unlock an old database. The custom encryption key guide describes how it is supplied.
n8n 3 enables data-encryption-key rotation by default. This uses a master instance key to protect data encryption keys stored in the database. Preserve both the database and the master key. Rotation is not permission to replace N8N_ENCRYPTION_KEY casually. Older n8n versions cannot read the new encrypted format, according to the rotation documentation.
If credentials fail after a restore, first compare secret references and mount locations with the manifest. Confirm the intended database and original key were restored together. Do not edit encrypted database values or toggle encryption settings as an experiment on the only recoverable copy.
Rehearse without sending duplicate real-world actions
An isolated database alone does not make a restored automation server safe. Published workflows can still send mail, create invoices or consume live messages when the copy starts. Before its first start, block production ingress and external actions at the network layer. Use separate database credentials and storage paths; never point staging at the production database.
Then replace live integration credentials with sandbox accounts and control which workflows are published. If an integration has no sandbox, use a controlled destination or a stub and record the untested part. Do not let staging register webhooks against the same production integration without checking how that service handles registration.
Build a small acceptance matrix:
| Case | Evidence to save |
|---|---|
| Scheduled workflow | Expected next run, timezone and one controlled execution. |
| Webhook | Accepted signed test event, response and one intended downstream action. |
| Credentials | Successful read-only or sandbox request using a restored credential. |
| Binary file | Upload, processing and retrieval of a representative attachment. |
| Retry path | Simulated transient failure and confirmation that it does not duplicate the business action. |
Use concrete business expectations: one test order produces one sandbox record and one sandbox notification. Check empty input, multiple items, large attachments and a slow external response where relevant. Save the workflow version, input and expected result so the same check can be repeated after stable arrives.
Our managed n8n deployment guide and managed apps versus VPS guide can help clarify which operational responsibilities you want to retain.
Prepare production cutover and a real recovery path
- Choose the release. Recheck stable availability and release notes; repeat the rehearsal if the candidate changes materially.
- Control incoming work. Pause triggers or upstream delivery, drain executions and document how missed events will be replayed.
- Take the final coordinated backup. Capture the database, files and secret references after writes have stopped.
- Upgrade the deployment. Follow the procedure for your installation and keep all participating processes on the intended compatible version.
- Validate before reopening. Check startup migrations, worker connectivity, credentials and the acceptance matrix.
- Resume gradually. Watch failure counts, pending work and duplicate business actions, not just container health.
Going back from 3.x means restoring the pre-upgrade backup, not starting a 2.x image against the upgraded database. Decide beforehand how to handle actions completed after cutover. Restoring an earlier execution record does not unsend an email or cancel an invoice; replaying it may perform that action twice.
Use business identifiers and downstream records to reconcile uncertain executions before retrying. Keep a named decision maker available for the whole window. Plan the interruption from your own rehearsal rather than assuming that every deployment needs only a container restart.
For a hosting option, explore DanubeData n8n hosting. Confirm the available stable version and the backup and upgrade responsibilities for your deployment before moving production workflows.
Frequently asked questions
Is n8n 3 stable yet?
As of 1 November 2026 it is a beta. The announcement targets early December for stable. Recheck the official release information when you schedule the change.
Can I go straight from n8n 1 to 3?
The announced path is through 2.x first. Make each transition recoverable and use the latest 2.x Migration Report before attempting 3.x.
Are workflow exports enough if the upgrade fails?
No. They are useful portable copies, but full recovery also needs the database, original encryption material, configuration and any separately stored files or custom nodes.
Can I recover credentials if the key is lost?
A restored encrypted database still requires its original encryption material. Search your protected secret store and complete user-folder backups. Creating a replacement key does not decrypt old credentials; affected integrations may need to be reauthorized.
Sources and further reading
- n8n 3.0 announcement and support timeline
- Version 3 breaking changes
- Migration Report guide
- Full-instance backup and restore
- Encryption key rotation and downgrade limits
