n8n
n8n 3.0 Breaking Changes: What to Fix Before You Upgrade
n8n 3.0 is in beta, with stable due in early December 2026. See what breaks, how to run the migration report, and a four-week plan to upgrade safely.
4 Nov 2026 · 10 min read · Abhijeet Singh

On this page 9 sections
n8n 3.0 entered beta on 27 October 2026, with the stable release expected in early December, and unlike most n8n releases it is not about new features. n8n describes it as an operational release: breaking changes, removals and legacy cleanup. If your business runs on n8n, the n8n 3.0 breaking changes decide whether your workflows keep running the morning after the upgrade, or whether a sub-workflow call, an old AI agent or a long-running Code node quietly starts failing.
The 3.0.0 beta is available now, and n8n says the stable release follows in early December 2026. That leaves a few weeks, which is enough if you start now. This guide covers what n8n has confirmed, what its built-in migration report checks, and the order we work through it for clients.
What n8n 3.0 is, and what is still unconfirmed
n8n shipped the 3.0.0 beta on 27 October 2026, and its developer guide on GitHub calls it an operational release rather than a big-bang feature launch. The breaking changes live on a separate 3.x branch, so your current 2.x instance only shows deprecation warnings.
Three things to know before you plan:
- The public page is incomplete. Items such as more secure credential behaviour are listed without detail, and n8n says migration guides will follow.
- The migration report checks more than the page lists, because it reads your actual configuration and workflows.
- 2.x has a fixed support window. n8n says that after the 3.0 stable release, 2.x gets security and critical bug fixes for 12 months. That is time to plan properly, not a reason to wait.
Start with the n8n 3.0 migration report
The most useful thing n8n has shipped for this upgrade is easy to miss. On 8 September 2026, n8n switched its built-in migration report over to 3.0 checks, shipping it in 2.38.5 on the stable line and 2.39.1 on beta the next day. It was tagged as a no-changelog change, so it is not in the release notes.
On 2.38.5, 2.39.1 or anything newer, open Settings and then Migration report. Going by n8n's documentation of the same tool for 2.0, it is available to global admins only and splits findings into two tabs:
- Workflow issues, listing each affected workflow with its published state, the nodes involved, its total executions and when it last ran.
- Instance issues, covering environment variables and deployment settings for the whole instance.
In the current rule set, only one check is marked Critical: AI Agent nodes still using agent modes that 3.0 removes, because those nodes fail when executed. Most other checks are Medium or Low.
Use the execution data to triage. A workflow that is unpublished and has not run in six months should be archived, not migrated. In our experience, that step alone removes a good share of the work before anyone edits a node.
Self-hosted on npm? Docker becomes mandatory
n8n 3.0 drops support for self-hosted installs run with npm or npx, and the newer n8n Assistant already requires Docker. If your instance was installed with a global npm command on a VPS, this is probably your largest single task.
The migration report's recommendation is the right frame: move to the official Docker image before updating, reusing your existing database and encryption key. The key is the part people lose. n8n generates it on first launch, saves it in the ~/.n8n folder and uses it to encrypt every stored credential. Start a fresh container without it and your workflows will still be there, but n8n cannot decrypt the credentials they depend on.
A safe sequence:
- Back up the database and copy the encryption key somewhere secure, off the server.
- Build a Docker Compose setup that uses your existing database and passes the same key through
N8N_ENCRYPTION_KEY. - Start it against a copy of your data and confirm credentials work by running a few real workflows.
- Cut over in a quiet window, and stop the old npm process so two instances never share one database.
For new installs, n8n offers a one-line setup script that installs n8n with Docker Compose. For existing npm users, n8n says step-by-step migration guidance is coming soon.
Nodes, modes and helpers that disappear
Legacy nodes
The v3.0 page names four removed nodes: Function, Function Item, Item Lists and the legacy LangChain Code node. Replace Function with the Code node in Run Once for All Items mode, Function Item with Code in Run Once for Each Item mode, and Item Lists with whichever of Split Out, Aggregate, Sort, Limit, Remove Duplicates or Summarize matches what you used.
The migration report's list is longer. It also flags Cron and Interval (use Schedule Trigger), Read Binary File and Write Binary File (use Read/Write Files from Disk), Read PDF (use Extract From File), HTML Extract and the original OpenAI node, plus early AI nodes such as Manual Chat Trigger, OpenAI Model and the separate Insert and Load versions of the Pinecone and Supabase vector store nodes. Workflows untouched since n8n's first AI wave are where these hide.
AI Agent version 1 and its agent types
Version 1 of the AI Agent node offered several agent types: SQL Agent, Conversational Agent, OpenAI Functions Agent, Plan and Execute Agent and ReAct Agent. n8n 3.0 removes version 1 and those modes, and an affected node fails when executed until you replace it.
Workflows already set to Tools Agent keep behaving the same once updated. For SQL Agent use cases, n8n recommends a Postgres or MySQL tool sub-node attached to a recent AI Agent node.
Do not treat this as a find-and-replace. A prompt tuned for a ReAct or Conversational agent can behave differently under the Tools Agent, especially around when it calls tools and how it formats answers. Rebuild the node, reconnect its model, memory and tools, then run the test inputs you used when you first built it and compare outputs before you publish.
Sub-workflow changes
Three changes affect the Execute Sub-workflow node, previously called Execute Workflow:
- The Local File and URL sources are removed. Switch to the Database source, or paste the workflow JSON into the Parameter source.
- The "Run once for each item" mode is removed. Put a Loop Over Items node in front and set the sub-workflow node to "Run once with all items".
- The "Any workflow" caller policy is removed. n8n deprecated it in 2.37, released in late August, because it lets any project on the instance call that sub-workflow, bypassing project permissions.
The caller policy change fails at run time, not at upgrade time. Give each affected sub-workflow a policy of "Selected workflows", listing the calling workflow IDs, or the same-project option. If your instance sets N8N_WORKFLOW_CALLER_POLICY_DEFAULT_OPTION to any, change it now: the report says 3.0 rejects that value and falls back to same-owner calls only.
Expression helpers
The undocumented $getPairedItem helper is removed. n8n has flagged it as deprecated in the expression editor since 2.30 in July. Replace it with standard item linking, using the pairedItem property or the item reference on a named node.
Security defaults that change behaviour
Some 3.0 changes remove nothing. They tighten defaults, so anything that silently relied on an old default behaves differently. The fix is usually one environment variable, set explicitly before you upgrade:
- Compression node limits drop. Maximum decompressed size falls from 2 GiB to 256 MiB, and maximum ZIP entries from 5,000 to 1,000. For large archives, set
N8N_COMPRESSION_NODE_MAX_DECOMPRESSED_SIZE_BYTESandN8N_COMPRESSION_NODE_MAX_ZIP_ENTRIESto the old values. - The Code node timeout shortens. The report warns the default task timeout falls from 300 seconds to 60. Set
N8N_RUNNERS_TASK_TIMEOUTto 300 if you have longer tasks. - Unverified community packages stop loading by default. Set
N8N_UNVERIFIED_PACKAGES_ENABLEDto true or, better, replace the package. - SSRF protection blocks more ranges. If you have switched SSRF protection on, its block list grows to include 100.64.0.0/10, the range Tailscale assigns device addresses from, so workflows reaching internal services over Tailscale will fail unless you allow those hosts.
- Queue mode sends manual runs to workers.
OFFLOAD_MANUAL_EXECUTIONS_TO_WORKERSgoes away and manual executions always run on workers, so size workers for it. - Project roles get external secrets. On Enterprise, project editors and admins get external-secrets access by default; use custom project roles to restrict it.
Key rotation makes the upgrade one-way
The v3.0 page lists key rotation as enabled by default. n8n's documentation for the current, opt-in version of encryption key rotation is blunt: enabling it is a one-way change, older n8n versions cannot read credentials written in the new format, and the only recovery path is a database backup taken before it was switched on.
So plan the 3.0 upgrade as one-way. Your rollback plan is a full database backup taken immediately before the upgrade, stored with the encryption key, not a version number you can flip back to.
Quieter behaviour changes to check
A few findings will not stop a workflow outright but will change what it does:
- Gmail Trigger. In 3.0, Gmail Trigger nodes older than version 1.4 run with 1.4 behaviour: at most 10 emails per poll by default, drafts excluded unless Include Drafts is on, and sent or scheduled emails no longer trigger the workflow. If an automation watches your sent folder, rebuild it as a Schedule Trigger plus a Gmail search.
- Embedded chat widgets. The chat connection moves to JSON messages. If you embed n8n's chat widget on your website with a pinned version, update it. Unpinned embeds update automatically.
Features on the way out: Chat Hub and import from URL
Chat Hub is switched off by default in 3.0. You can turn it back on for 3.x, but n8n says its AI assistant and agents are replacing it, so treat it as a feature on its way out. Teams that adopted it used it as a front door: a chat interface for n8n agents, plus a Chat user role for people who should never see the editor.
If non-technical staff trigger workflows through Chat Hub today, two replacements work now. For launching a process, a Form Trigger with n8n user authentication, branching into sub-workflows and ending on a completion screen, is the approach an n8n community moderator recommended on the official forum. For conversational agents, move the conversation to where your team already works, such as Slack, Microsoft Teams, Telegram or WhatsApp.
Workflow import from URL in the editor is also removed. Copy-paste, Import from File, the CLI and the API remain.
A four-week n8n 3.0 upgrade plan
Week 1: inventory. Update to the latest 2.x stable release, run the migration report and move findings into a simple tracker. Archive dead workflows. Back up the database and store the encryption key off the server.
Week 2: infrastructure. Move npm installs to Docker. Set explicit values for any default you rely on: task timeout, compression limits, unverified packages and the caller policy default. Doing this early means each behaviour change lands when you choose, not during the version bump.
Week 3: workflows. Fix the Critical AI Agent findings first, then caller policies, then legacy nodes and expressions. Test on a staging instance with realistic data and re-run the report until both tabs are clean.
Week 4 and beyond: upgrade deliberately. Do not upgrade on release day. n8n ships patches fast; the 2.38 line went from 2.38.1 to 2.38.7 in about ten days this September. Upgrade staging first, watch it for a few days, then production, with a backup taken that morning.
On n8n Cloud, deployment and environment-variable items are n8n's job, but workflow findings are yours. Instance owners control the version, release track and update cadence in the Cloud dashboard, and n8n recommends the Stable track for mission-critical workloads. Cloud owners can already pick the 3.0.0 beta as an early-access version, but for mission-critical workspaces wait for stable and check those settings now.
How we handle n8n 3.0 for clients
At AbhijeetBuilts, we treat a major n8n upgrade like any other production change: inventory, fix, test, then release with a rollback plan. For self-hosted clients, that means running the migration report, archiving what is dead, moving npm installs to Docker with the database and key carried over, rebuilding old AI agents against their original test cases, and upgrading in a quiet window with a fresh backup. The workflows that cause trouble are rarely the complex ones. They are the small automations someone built two years ago that nobody has opened since.
If you run n8n and are not sure what 3.0 will break, get in touch through our website. We can run the migration report with you, size the work honestly and handle the upgrade end to end.
Related resources
Keep building the automation map
Move from the guide into the services and proof pages connected to this topic.
Related services
Service
Explore n8n Workflow Development
Custom n8n workflow automation for lead capture, CRM sync, AI enrichment, approvals, and notifications — built to keep running when nobody is watching.
Service
Explore AI Agent Development
AI agents for sales replies, lead memory, storyboard generation, data extraction, and structured automation outputs.
Service
Explore AI Operating System
A done-for-you AI operating system built on Claude: a second brain that knows your business, remembers everything between sessions, and safely runs your recurring work.
Further reading
Article
Read: The n8n 2.0 Upgrade in 2026: What Breaks and What to Fix
The n8n 2.0 upgrade changed defaults, not features. Here is what breaks in 2026, which environment variables to test first, and a migration order that works.
Article
Read: n8n vs Make in 2026: Pricing, Limits and Trade-Offs
n8n vs Make in 2026: how execution billing beats per-module credits, where each platform wins, and the n8n 3.0 migration to plan for before you commit.
Article
Read: n8n Access Control in 2026: Projects, Roles and Limits
n8n access control explained: instance roles versus project roles, where projects stop isolating data, and the credential leak most teams miss.
Proof pages
Case study
See case study: Zapier to n8n Migration for a US Manufacturer: $70 a Month Down to $10
About 20 lead and attribution workflows moved from Zapier to self-hosted n8n, taking the automation bill from about $70 a month to a $10 server the client owns.
Case study
See case study: Multilingual WhatsApp Sales Bot for an International Freight Forwarder
A WhatsApp AI sales assistant that qualifies freight enquiries in three languages, remembers every conversation, and alerts the sales team the moment a quote is requested.