n8n 3.0 Upgrade Guide: What Breaks and How to Prepare

On October 27, n8n published version 3.0.0 as a beta. According to n8n's announcement, the stable release follows in early December. If you run n8n in production, that puts a date range on your calendar, and two questions come with it. Will my workflows break? And how do I find out before they do?

Here is the complication. n8n 3.0 is not a feature release. The team says it has shipped over 45 releases since 2.0 arrived in December 2025, and new features have been landing all along. What 3.0 collects is everything that had to wait for a major version number: legacy nodes removed, defaults tightened, a few features retired. It is the kind of release where a workflow that ran fine on Friday fails on Monday for a reason nobody remembers choosing.

The turn is that n8n gave you a tool for this, and it is available now. Before we get to it, I want to be plain about what changes, in what order I would worry about it, and why I would not upgrade a production instance this month.

What shipped, and the dates that matter

The GitHub release for [email protected] is marked as a pre-release and was published on October 27, 2026. That is the beta. It is not the stable version, and nothing below should be read as a claim that 3.x is ready for production.

The facts n8n has stated are short. Stable is planned for early December, and n8n has not given a firmer date, so I will not either. Everything in 3.0 applies to self-hosted Community, Cloud, and Enterprise or Business plans. After stable, 2.x gets security and critical bug fixes for 12 months, and new features ship on 3.x only. If you are still on 1.x, there is no direct path to 3.x. You go to 2.x first, and support for 1.x ends on December 31, 2026.

Then there is the line that should shape your whole plan. Moving to 3.x is one way. n8n says there is no going back to 2.x, so a rollback means restoring a backup you took before you upgraded. Treat that as the design constraint.

Should you upgrade production now?

No. That is my judgment, not n8n's wording. n8n says the beta is worth a look "even if you're not planning to upgrade right away," and I agree with that half. I would not take the other half and run it against production.

A one-way upgrade, a beta label, and a stable date a few weeks out add up to a simple rule. Do the learning on a copy of your instance. Do the production move after stable ships, once you have cleared what the Migration Report flags and rehearsed the whole thing on staging.

If you are on n8n Cloud, the beta appears as 3.0.0 Beta (early access) when you change your n8n version. Self-hosted, you install it like any other beta release. Either way, use a test instance, and take a full backup first, because the one-way rule applies to the test instance too.

What breaks first, in the order I would worry about it

n8n's v3.0 breaking changes page is the full list, and it is long. You do not need to hold all of it in your head. You need a ranking for a stack with AI steps, scheduled jobs, and a few integrations nobody has touched in a year. The ranking is mine. Each item points back to what the docs say.

First, removed nodes and the old AI Agent modes. The docs are direct: workflows that use a removed node fail. The list includes the legacy Function, Function Item, and Item Lists nodes, Cron and Interval, HTML Extract, Read PDF, Workflow Trigger, the legacy OpenAI node, and several memory and vector store nodes. Many have a direct replacement. Function becomes the Code node, and Cron and Interval become the Schedule Trigger. A few, like LangChain Code, have none. These come first because failure is certain.

Second, the Slack signing secret. n8n 3.0 requires a signing secret on the Slack API credential. If a workflow uses a Slack Trigger node, add the secret before you upgrade. Until you do, the docs say the workflow fails to publish and the trigger responds with a 401 error. The fix takes minutes: copy the Signing Secret from your Slack app's Basic Information page, paste it into the credential, and publish again. It ranks second because it is cheap to fix and expensive to miss.

Third, the Code node timeout and the Compression limits. The default task runner timeout, N8N_RUNNERS_TASK_TIMEOUT, drops from 300 seconds to 60, and Code node tasks that run longer fail. The Compression node's default decompression limit drops from 2 GiB to 256 MiB, and its zip entry limit drops from 5,000 to 1,000. If you rely on the old values, the docs tell you to set the variables explicitly before upgrading. These are the quiet ones, because nothing errors during the upgrade itself.

Fourth and fifth, npm installs and the storage path. Both are deployment questions, so they get their own section below.

Sixth, unverified community nodes. N8N_UNVERIFIED_PACKAGES_ENABLED changes its default from true to false. After the upgrade you cannot install unverified community nodes from npm, and installed ones stop loading. You can set the variable back to true or move to verified nodes. That is a security decision, so make it on purpose.

A few smaller changes deserve a line. The default SSRF block list gains four ranges, so calls to hosts in them fail unless you allow them. The Gmail Trigger node on versions below 1.4 now runs with 1.4 behavior, which skips drafts unless you turn on Include Drafts. Import from URL is gone from the editor, and so is the Ask AI tab in the Code node.

Where AI workflows get hit

This is the part I would read twice if your agents were built in 2024 or 2025.

Version 1 of the AI Agent node supported several agent type modes: SQL, Conversational, OpenAI Functions, Plan and Execute, and ReAct. n8n 3.0 removes version 1 of the node along with those modes. The latest version replaces them with the Tools Agent, and per the docs, workflows already set to Tools Agent behave the same after you update. For SQL Agent use cases, the suggested replacement is a Postgres or MySQL tool sub-node paired with a recent AI Agent node.

The OpenAI side changes too. The legacy OpenAI node, the OpenAI Assistant node, and the OpenAI Model node are removed. The docs point to the current OpenAI node, including its Assistant resource, and to the OpenAI Chat Model node. The legacy HTTP Request Tool is replaced by the HTTP Request node connected to the AI Agent node's tool input. AI Transform is the gentle one: n8n migrates existing AI Transform nodes to Code nodes on upgrade and keeps the same generated JavaScript, though you can no longer add a new one.

Why does this section matter more than the others? Because a swap that is simple on paper is a behavior question in practice. Moving an agent to the Tools Agent changes a node version. Whether the agent still answers the way your team expects is something only a test run will tell you. Check the output, not just whether the workflow executes. It is the same point I made about guardrails for AI-drafted n8n workflows in production: a workflow that runs is not the same as a workflow that is correct.

Self-hosting: Docker, storage paths and queue mode

If you self-host, three changes touch how n8n runs, not just what it runs.

Docker is now required. Self-hosted n8n 3.0 no longer supports installs run with npm or npx n8n, and it does not publish a runnable n8n package to npm. n8n says part of the reason is that new security features depend on a container setup. If you are on npm today, move to Docker before you upgrade. The docs offer a one-line setup, curl -fsSL https://get.n8n.io | sh, that checks Docker, writes the configuration files, and starts a new instance. If you already run your own Docker Compose file, you do not need to switch, and Kubernetes and Helm deployments are not affected. If you are still choosing a hosting route, my decision guide to one-click n8n installation platforms covers the tradeoffs.

The storage directory is renamed. On first start, n8n 3.0 renames ~/.n8n/binaryData to ~/.n8n/storage. If both directories exist, n8n will not start. It stops with an error instead of guessing. If you mount a volume at the old path, mount it at the new one, or set N8N_STORAGE_PATH to keep the old path. If both exist, the docs say to move the contents of binaryData into storage, remove binaryData, and start again. Related: the in-memory binary data mode is removed, and instances still set to default switch to filesystem on upgrade, so check that the mounted disk has room.

Queue mode shifts load to workers. Manual executions now always run on workers, and OFFLOAD_MANUAL_EXECUTIONS_TO_WORKERS is removed. That keeps the main instance from doing that work, which is the point. The consequence is yours to manage: workers now handle manual runs too, so review the memory you give them.

Using the Migration Report without drowning in it

Now the tool. Every instance on version 2.39 or later has a Migration Report at Settings > Migration Report, and n8n recommends updating to the latest 2.x first because that has the newest version of the report. As the migration tool docs explain, you do not need to be an admin to open it. Admins see every workflow, and other users see the workflows they can edit.

At the top, a progress bar shows how many of your workflows are compatible with 3.0. Two tabs sit under it: Workflow issues, and Instance issues for owners and admins, which covers environment variables and deployment settings. Each issue carries one of five impact levels. Upgrade blocked means the upgrade cannot proceed or the instance may not start, so fix it first. Executions will fail comes next, then Executions might fail, Behavior changes, and finally Capability removed, where executions are not affected but a feature you use is gone.

For some issues, the report can fix the workflow for you. Select Migrate, review the nodes it will change, and confirm. n8n saves the result as a new workflow version, and a published workflow keeps running its current version until you publish the new one. The docs add a caution I would underline: the automatic migration covers node changes only, so check that the output still matches what you expect.

The report also suggests an owner for each workflow, based on who last worked on it. Admins can reassign owners and, if SMTP is set up, email them. You can mark obsolete workflows as "won't fix," sort by most runs to fix your busiest workflows first, and export a CSV to share progress. An empty report is not a finish line either. The docs still tell you to review the breaking changes page for anything the tool cannot detect.

The owner column also supports a habit from my n8n production case study for US service firms: somebody has to own each workflow.

A rehearsal plan for the weeks before stable

n8n's own recommended path is four steps: update to the latest 2.x and open the report, fix or mark "won't fix" everything it flags, take a full backup, and upgrade a test or staging instance first, then production. Here is how I would spread that across the weeks before stable.

1. Update to the latest 2.x, open the Migration Report, and read both tabs before changing anything.
2. Clear Upgrade blocked and Executions will fail first, then work down.
3. Add the Slack signing secret to any credential behind a Slack Trigger workflow.
4. Set environment variables explicitly wherever you depend on an old default.
5. Move off npm or npx if that is how you run n8n, and fix volume mounts for the new storage path.
6. Take a full backup, and confirm you can restore it.
7. Upgrade a staging copy to the beta, run your busiest workflows, and compare outputs.
8. Repeat on the stable release when it ships, then schedule the production window.

The last step is a repeat on purpose. Beta docs can change before stable, so re-read the breaking changes page the day you upgrade.

What to watch before stable

Watch n8n's release notes and the breaking changes page, because that is where changes to the plan will show up. I will not predict features n8n has not announced. The team says the focus of 3.0 is reliability, stability, and security. It published no benchmarks, so do not expect faster workflows just because the version number went up.

If you remember three things, make them these. The upgrade is one way, so the backup and the staging copy are your rollback plan. The Migration Report is the fastest honest answer to "will my workflows break," so update to the latest 2.x and run it this week. And the risk concentrates in a few places: removed nodes, the old AI Agent modes, the Slack signing secret, and the new timeouts and limits. Start there, and the rest is cleanup.

You have weeks, not days. Open Settings > Migration Report, read what it says, and set your production date after that, not before.