Preflight · Guides

n8n 3.0 upgrade: how to test your workflows before you upgrade

By Preflight · Published 24 October 2026 · Updated 24 October 2026

Before upgrading to n8n 3.0, run the Migration Report and fix what it lists, then check that your important workflows still produce the same output on 3.0 using a copy of your instance, never production. The report finds known incompatibilities; only running your own workflows on your own data shows whether their behavior changed.

Where n8n 3.0 stands, 24 October 2026: n8n’s breaking-changes page says 3.0 is “releasing soon”. Docker Hub’s stable tag is 2.44.6 and beta is 2.45.3; 3.0 is published only as v3-nightly builds, which are not for production, and which still report their version as 2.45.0. This page will be updated when 3.0 ships.

What changes in n8n 3.0?

n8n 3.0 requires Docker for self-hosting, removes a long list of legacy nodes and helpers, and changes several defaults that can alter how existing workflows run. n8n’s breaking-changes page groups them into deployment, removed nodes and helpers, behavior changes, security and configuration; the ones most likely to touch a production instance are below.

• Docker only. Installs run with npm or npx n8n are not supported.
• Removed nodes. Function, Function Item, Item Lists, Cron, Interval, HTML Extract, Read PDF, Read and Write Binary File, Workflow Trigger, the legacy OpenAI node and others. Workflows that use them fail.
• Removed helpers. $getPairedItem in expressions, version 1 of the AI Agent node with its older agent modes, and the Local File and URL sources of Execute Sub-workflow.
• Behavior changes. Always Output Data on If and Switch nodes, and Gmail Trigger versions below 1.4 now run with version 1.4’s behavior.
• Security. Slack Trigger workflows need the Slack signing secret, four more IP ranges are blocked when SSRF protection is on, and the Compression node’s limits drop.
• Configuration. The Code node task timeout falls from 300 to 60 seconds, unverified community packages are off by default, and ~/.n8n/binaryData is renamed to ~/.n8n/storage; n8n will not start if both exist.

What does n8n’s Migration Report catch?

The Migration Report, under Settings › Migration Report, lists the workflows and instance settings on your own instance that n8n knows 3.0 affects, down to the nodes involved. Start there: a workflow it lists for a removed node or helper will fail on 3.0 unless you replace that node first.

n8n’s breaking-changes page gives the replacement for each removed node, for example the Code node for Function and Function Item, and the Schedule Trigger for Cron and Interval. n8n’s documentation of the same tool for the 2.0 upgrade limited it to global admins, so if you cannot see it, that is the likely reason.

What can’t the Migration Report tell you?

It cannot tell you whether a workflow still produces the same output on 3.0. It names the nodes a behavior change touches, but whether the change matters depends on your data, and a change n8n did not list is not in it.

• Always Output Data on If and Switch. Before 3.0, each empty output got an empty item, so a branch could run when it should not have. Now the empty item is added only when every output is empty. If one of your branches relied on that, it stops running, without an error.
• The 60-second Code timeout. A task that took 70 seconds on last month’s volume fails on 3.0. How long your tasks take on real data is not something a static report can know.
• The SSRF ranges. With SSRF protection on and the default list, 3.0 also blocks 100.64.0.0/10, the range Tailscale assigns its devices. A workflow that calls a service over Tailscale can break.
• The unlisted. Past n8n releases, minor ones included, have changed runtime behavior in ways no list predicted. That is why the check that counts is running your own workflows.

How do I test my workflows on n8n 3.0 without touching production?

Export your workflows, import them into a brand-new n8n instance running the 3.0 image, and run each important one there on real inputs copied from production, with every node that reaches the outside world pinned to its recorded output. Then compare each node’s output with the production execution it came from. A fresh instance holds no production credentials, no production database and no waiting executions, so there is nothing in it that can act on a client system by itself.

1. Export the workflows only. On production, n8n export:workflow --all --separate --output=workflows/ writes one file per workflow. Credentials and execution history are not included, and that is the point.
2. Start a new instance on the image you are testing, with its own container, volume and database, sharing nothing with production: not its database, not its Redis queue, not its settings file. Pin the exact image: a v3-nightly build today, the 3.0 release once it ships.
3. Import them with n8n import:workflow --separate --input=workflows/. In our test, importing into a 3.0 nightly left every workflow unpublished, including one that was published on the source, so no schedule or webhook goes live.
4. Pin the real inputs and the outside world. For each workflow, open a recent successful execution on production and copy the output of its trigger, and of every node that calls an outside service, into the matching node in the test instance as pinned data. n8n’s documentation describes copying data from a past execution this way. Nodes that need a credential will fail without one, which is safe; nodes that call a URL without one will not, so pin those without exception.
5. Test sub-workflows on their own. Pins inside a sub-workflow are ignored when a parent calls it, so pin the parent’s Execute Sub-workflow node to its recorded output, and test the sub-workflow separately with its own pins.
6. Run and compare. Execute each workflow and compare every unpinned node’s output with the production execution. A difference explained by a listed change is a fix to make before you upgrade. One you cannot explain is the important one.

If you can, run the test instance without internet access as well: it is the only precaution that also covers a node you forgot to pin. Restoring a full backup into a copy looks quicker and is riskier: the copy needs production’s encryption key to start at all, which hands it your real credentials, and executions that were waiting in production resume in the copy and finish for real; we watched one do so after the copy’s workflows were unpublished.

This works, and it is slow: one execution at a time, pinned by hand and compared by eye. For a handful of critical workflows it is worth the afternoon. Across many client instances it is the part people skip.

How does Preflight’s upgrade check do this?

Preflight replays each workflow’s latest recording on the target n8n version in its own sandbox, and on the current version as a control, then compares both with the recording. A workflow that diverges only on the target version breaks on the upgrade; one that diverges on both was already unstable and is reported flaky, not blamed on the upgrade. The client’s server is never touched, and Preflight never reads the credentials stored on it.

Its limits are part of the answer. Because a replay never calls outside services, a workflow with HTTP or side-effect nodes it cannot vouch for comes back untestable, with the count and the reason. Most real workflows contain such a node, so untestable is a common answer, and it is never folded into safe. The check runs only on an n8n version it can drive and confirm in its sandbox, and declines one it cannot. It has only been run live on one version jump, 2.33.7 to 2.35.7, on Preflight’s demo workflows, has not yet been run on 3.0, and has not yet found a real break to report on live data, so its “breaks” verdict is tested in code but not yet seen in the field. Preflight is in beta for the waitlist.

What should I check right after upgrading?

Check that every scheduled workflow fires on time and every production webhook still answers, by watching for the next real execution of each, not by trusting the published badge. Upgrades and restarts have left n8n triggers registered in the editor but silent before, and the error workflow cannot report a run that never started.

Keep the previous image tag written down and the pre-upgrade backup to hand until a full cycle of schedules has run. Because the database only migrates forward, rolling back means restoring that backup, not just changing the tag.

The same method for everyday edits: how to test n8n workflow changes before production.